{"info":{"_postman_id":"8a1e2b3f-af2c-4fd7-8a50-02ca83f6db23","name":"Botpress Messaging API Integration","description":"

This is a simple integration for sending messages to your bot via API and recieving responses.

\n

You can use this to send messages or other information back and forth between your bot and any back-end application.

\n

How it works

\n

You configure a webhook url for catching responses from your bot. Your bot may receive several responses for a single incomming message scattered through time. Each webhook invocation sends a single message back to your service.

\n

The body of a webhook response should look like this:

\n
type WebhookResponse = {\n  type : string, \n  payload : any, // contains the response text or metadata otherwise\n  conversationId: string, // use this to send the response to the write location\n  botpressUserId: string, // botpress user id for debugging \n  botpressMessageId: string, // botpress message id for debugging \n  botpressConversationId: string, // botpress conversation id for debugging\n}\n\n
\n

You use the API endpoint below to send messages. When sending messages to your bot, you provide a conversationId parameter that will be sent back to your webhook url, so that you may identify where to send your bot's responses.

\n

Getting started

\n
    \n

  1. Install this integration to your bot.

    \n
    2. \n

  2. To authenticate your messages, include a Personal Access Token you can get 👉 here 👈 .

    \n
    3. \n

  3. In your bot's integration page, find the Botpress api integration.

    \n
    4. \n

  4. Add your webhook url to the externalWebhookUrl configuration option. This will recieve responses.

    \n
    5. \n

  5. On the same page, copy the provided Webhook URL, this will be the endpoint for creating messages.

    \n
    6. \n

  6. Send your first message using the instructions below.

    \n
    7. \n
\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[],"owner":"20577045","collectionId":"8a1e2b3f-af2c-4fd7-8a50-02ca83f6db23","publishedId":"2s9YsDjEqu","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"5291ff"},"publishDate":"2024-01-03T15:37:09.000Z"},"item":[{"name":"create message","id":"b2cc75be-eb16-4e7f-a695-1f39598d27e2","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"userId\": \"remoteUserId\",\n \"messageId\": \"remoteMessageId\",\n \"conversationId\": \"remoteConversationId\",\n \"type\": \"text\",\n \"text\": \"Any text you want to send, otherwise a short description of what you are sending\",\n \"payload\": {\n \"foo\": \"bar\",\n \"user\": {\n \"userName\": \"Robert\"\n }\n }\n}","options":{"raw":{"language":"json"}}},"url":"YOUR_APPS_INTEGRATION_WEBHOOK_URL/messages","description":"

This allows you to send messages from your integration to Botpress. It responds with the created or existing user, message and conversation objects.

\n
Body parameters
\n
type BodyParameters = {\n  userId: string; // ensures that the message is added for the correct user, in case of multiple users\n  messageId: string; // helps prevent duplicates\n  conversationId: string; // identifies the conversation uniquely and is used for sending back responses\n  type: string; // should be 'text' if the message type is text, otherwise a different string for other types\n  text: string; // the text of the user's message if the type is text, or a summary of the payload for other types\n  payload: any; // an object containing any data you want to send, specific to the message type\n}\n\n
\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"YOUR_BOTPRESS_PAT"}]},"isInherited":true,"source":{"_postman_id":"8a1e2b3f-af2c-4fd7-8a50-02ca83f6db23","id":"8a1e2b3f-af2c-4fd7-8a50-02ca83f6db23","name":"Botpress Messaging API Integration","type":"collection"}},"urlObject":{"path":["messages"],"host":["YOUR_APPS_INTEGRATION_WEBHOOK_URL"],"query":[],"variable":[]}},"response":[{"id":"553d99d8-4292-47b8-944b-db53e8709a6c","name":"create pure text message","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"userId\": \"remoteUserId\",\n \"messageId\": \"remoteMessageId\",\n \"conversationId\": \"remoteConversationId\",\n \"type\": \"text\",\n \"text\": \"this is just some text\"\n}","options":{"raw":{"language":"json"}}},"url":"YOUR_APPS_INTEGRATION_WEBHOOK_URL/messages"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Date","value":"Fri, 29 Dec 2023 19:15:20 GMT"},{"key":"Content-Type","value":"application/json; charset=utf-8"},{"key":"Content-Length","value":"888"},{"key":"Connection","value":"keep-alive"},{"key":"X-Amzn-Requestid","value":"d38b1ca8-5da0-4ad3-a288-a3c0e0720f80"},{"key":"X-Amzn-Trace-Id","value":"root=1-658f1ac8-315d215b1b8d2eb003324bcf;sampled=0;lineage=e1d929d9:0"},{"key":"X-Powered-By","value":"Express"}],"cookie":[],"responseTime":null,"body":"{\n \"message\": {\n \"id\": \"12ddebc5-699c-46c5-9443-9b818fca33cb\",\n \"createdAt\": \"2023-12-29T19:15:20.626Z\",\n \"conversationId\": \"65c81a7a-d63c-4c54-89b1-60a16b23d70d\",\n \"payload\": {\n \"text\": \"this is just some text\"\n },\n \"tags\": {\n \"botpressapi:id\": \"remoteMessageId\",\n \"id\": \"remoteMessageId\"\n },\n \"userId\": \"87d33910-dbcc-4612-aeff-e0a0782e8455\",\n \"type\": \"text\",\n \"direction\": \"incoming\"\n },\n \"user\": {\n \"id\": \"87d33910-dbcc-4612-aeff-e0a0782e8455\",\n \"createdAt\": \"2023-12-29T18:50:36.986Z\",\n \"updatedAt\": \"2023-12-29T18:50:36.986Z\",\n \"tags\": {\n \"botpressapi:id\": \"remoteUserId\",\n \"id\": \"remoteUserId\"\n }\n },\n \"conversation\": {\n \"id\": \"65c81a7a-d63c-4c54-89b1-60a16b23d70d\",\n \"createdAt\": \"2023-12-29T18:50:36.866Z\",\n \"updatedAt\": \"2023-12-29T18:50:36.866Z\",\n \"channel\": \"channel\",\n \"integration\": \"botpressapi\",\n \"tags\": {\n \"botpressapi:id\": \"remoteConversationId\",\n \"botpressapi:foreignKey\": \"remoteConversationId\",\n \"id\": \"remoteConversationId\",\n \"foreignKey\": \"remoteConversationId\"\n }\n }\n}"},{"id":"5a2d34f8-2531-4b15-a4bc-d3ef61eea38d","name":"create text message with additional information","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"userId\": \"remoteUserId\",\n \"messageId\": \"remoteMessageId\",\n \"conversationId\": \"remoteConversationId\",\n \"type\": \"text\",\n \"text\": \"this is some example text message\",\n \"payload\": {\n \"tone\": \"happy\",\n \"userName\": \"Robert\"\n }\n}","options":{"raw":{"language":"json"}}},"url":"https://webhook.botpress.cloud/7c03285f-f507-43f2-bed7-5d462af8c590"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Date","value":"Fri, 29 Dec 2023 19:14:00 GMT"},{"key":"Content-Type","value":"application/json; charset=utf-8"},{"key":"Content-Length","value":"934"},{"key":"Connection","value":"keep-alive"},{"key":"X-Amzn-Requestid","value":"f7332374-de30-403d-a85f-caa93c87be79"},{"key":"X-Amzn-Trace-Id","value":"root=1-658f1a78-4f13183d0d5994370a2c83e2;sampled=0;lineage=e1d929d9:0"},{"key":"X-Powered-By","value":"Express"}],"cookie":[],"responseTime":null,"body":"{\n \"message\": {\n \"id\": \"e92b19b5-3ecd-411f-b8c6-fc0778cdacf5\",\n \"createdAt\": \"2023-12-29T19:14:00.414Z\",\n \"conversationId\": \"65c81a7a-d63c-4c54-89b1-60a16b23d70d\",\n \"payload\": {\n \"tone\": \"happy\",\n \"userName\": \"Robert\",\n \"text\": \"this is some example text message\"\n },\n \"tags\": {\n \"botpressapi:id\": \"remoteMessageId\",\n \"id\": \"remoteMessageId\"\n },\n \"userId\": \"87d33910-dbcc-4612-aeff-e0a0782e8455\",\n \"type\": \"text\",\n \"direction\": \"incoming\"\n },\n \"user\": {\n \"id\": \"87d33910-dbcc-4612-aeff-e0a0782e8455\",\n \"createdAt\": \"2023-12-29T18:50:36.986Z\",\n \"updatedAt\": \"2023-12-29T18:50:36.986Z\",\n \"tags\": {\n \"botpressapi:id\": \"remoteUserId\",\n \"id\": \"remoteUserId\"\n }\n },\n \"conversation\": {\n \"id\": \"65c81a7a-d63c-4c54-89b1-60a16b23d70d\",\n \"createdAt\": \"2023-12-29T18:50:36.866Z\",\n \"updatedAt\": \"2023-12-29T18:50:36.866Z\",\n \"channel\": \"channel\",\n \"integration\": \"botpressapi\",\n \"tags\": {\n \"botpressapi:id\": \"remoteConversationId\",\n \"botpressapi:foreignKey\": \"remoteConversationId\",\n \"id\": \"remoteConversationId\",\n \"foreignKey\": \"remoteConversationId\"\n }\n }\n}"},{"id":"dbf5b57e-8df8-4584-b862-f4723a5fc789","name":"sending non-text content","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"userId\": \"remoteUserId\",\n \"messageId\": \"remoteMessageId\",\n \"conversationId\": \"remoteConversationId\",\n \"type\": \"image\",\n \"text\": \"Here's an image I am sending you [attached]\",\n \"payload\": {\n \"imgUrl\": \"https://google.com/logo.png\"\n }\n}","options":{"raw":{"language":"json"}}},"url":"YOUR_APPS_INTEGRATION_WEBHOOK_URL/messages"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Date","value":"Fri, 29 Dec 2023 19:16:43 GMT"},{"key":"Content-Type","value":"application/json; charset=utf-8"},{"key":"Content-Length","value":"949"},{"key":"Connection","value":"keep-alive"},{"key":"X-Amzn-Requestid","value":"96b61770-c009-4578-a552-3f56e150fc85"},{"key":"X-Amzn-Trace-Id","value":"root=1-658f1b1b-0fac565b0760c1c36960ba13;sampled=0;lineage=e1d929d9:0"},{"key":"X-Powered-By","value":"Express"}],"cookie":[],"responseTime":null,"body":"{\n \"message\": {\n \"id\": \"a8d376f0-41f1-4ab7-a428-3e516fbc60a2\",\n \"createdAt\": \"2023-12-29T19:16:43.653Z\",\n \"conversationId\": \"65c81a7a-d63c-4c54-89b1-60a16b23d70d\",\n \"payload\": {\n \"imgUrl\": \"https://google.com/logo.png\",\n \"text\": \"Here's an image I am sending you [attached]\"\n },\n \"tags\": {\n \"botpressapi:id\": \"remoteMessageId\",\n \"id\": \"remoteMessageId\"\n },\n \"userId\": \"87d33910-dbcc-4612-aeff-e0a0782e8455\",\n \"type\": \"image\",\n \"direction\": \"incoming\"\n },\n \"user\": {\n \"id\": \"87d33910-dbcc-4612-aeff-e0a0782e8455\",\n \"createdAt\": \"2023-12-29T18:50:36.986Z\",\n \"updatedAt\": \"2023-12-29T18:50:36.986Z\",\n \"tags\": {\n \"botpressapi:id\": \"remoteUserId\",\n \"id\": \"remoteUserId\"\n }\n },\n \"conversation\": {\n \"id\": \"65c81a7a-d63c-4c54-89b1-60a16b23d70d\",\n \"createdAt\": \"2023-12-29T18:50:36.866Z\",\n \"updatedAt\": \"2023-12-29T18:50:36.866Z\",\n \"channel\": \"channel\",\n \"integration\": \"botpressapi\",\n \"tags\": {\n \"botpressapi:id\": \"remoteConversationId\",\n \"botpressapi:foreignKey\": \"remoteConversationId\",\n \"id\": \"remoteConversationId\",\n \"foreignKey\": \"remoteConversationId\"\n }\n }\n}"}],"_postman_id":"b2cc75be-eb16-4e7f-a695-1f39598d27e2"}],"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"YOUR_BOTPRESS_PAT"}]}},"event":[{"listen":"prerequest","script":{"id":"0838282f-3c20-4693-8c80-864305b4d082","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"eb1112fe-e976-405f-bdfa-d797db882380","type":"text/javascript","exec":[""]}}],"variable":[{"key":"BOTPRESS_PAT","value":"YOUR_BOTPRESS_PAT","type":"string"},{"key":"BOT_WEBHOOK_URL","value":"YOUR_APPS_INTEGRATION_WEBHOOK_URL","type":"string"}]}