{"info":{"_postman_id":"aa67955b-a37e-4dc5-92ef-4bf2066f651f","name":"Kiamo.io API Messaging / Bot","description":"

This API can be used by our partners to send and receive messages to and from Kiamo.
It enables the integration of external solutions into Kiamo (for instance: Chatbot, customized Messaging solutions)

Connector creation

The connector is created by Kiamo teams.
Once the connector has been created, you'll receive ClientId and ClientSecret credentials that will enable you to request an OAuth token for API calls.
The connector can only access one Kiamo instance. You will need to create as many connectors as there are Kiamos with which you wish to exchange messages.

OAuth2.0 authentication

Requests sent to the Messaging API must be authenticated using the OAuth 2.0 standard.
You will have to generate an access_token using the identifiers you were given (ClientId et ClientSecret) when you created your connector.
To generate the OAuth2.0 authentication token, you'll need to connect to the server: https://app.kiamo.io/oauth2/v1/token and use the client_credentials flow.

\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[],"owner":"8283488","collectionId":"aa67955b-a37e-4dc5-92ef-4bf2066f651f","publishedId":"2s946k4q2t","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"},"publishDate":"2023-07-20T09:58:46.000Z"},"item":[{"name":"Your webhook","item":[{"name":"Get messages from Kiamo","id":"8a57210e-f635-4d44-b98b-f9db3d8d7c86","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"id\": \"\",\n \"created_at\": \"\",\n \"customer_id\": \"\",\n \"sender\": {\n \"type\": \"human\",\n \"id\": \"\",\n \"name\": \"\"\n },\n \"body\": {\n \"message\": \"\",\n \"attachments\": [\n {\n \"id\": \"\",\n \"name\": \"\",\n \"mime_type\": \"\",\n \"content\": {\n \"type\": \"url\",\n \"data\": \"\"\n }\n },\n {\n \"id\": \"\",\n \"name\": \"\",\n \"mime_type\": \"\",\n \"content\": {\n \"type\": \"base64\",\n \"data\": \"\"\n }\n }\n ],\n \"rich_content\": {}\n },\n \"metadata\": {}\n}","options":{"raw":{"headerFamily":"json","language":"json"}}},"url":"{{Your_Webhook}}","description":"

Your webhook will be called by the Kiamo.io platform when a message is sent to your push's service.
Your webhook will receive a POST call.

Attachments:

For each attachment you will receive a URL to download the contents of the attachment.
Be sure to save attachments if necessary, as they will be deleted from our servers a few hours after recovery.

Response:

The webhook must respond with a HTTP code 200 if the message is well received. In case of another response code, kiamo.io will consider that the message did not arrive and will send it again during the next call of the webhook.

Validation of the content and origin of the message:

To ensure that the message received via your webhook has been sent from a secure source and has not been modified, we recommend using the Body-Hash HTTP header that you will receive in the requests to your webhook.

This header contains a hash of the content of the request (Body HTTP) created from the \"Hmac\" method with the \"sha1\" algorithm and using the Client Secret provided to you.

When you receive a request on your webhook, we therefore recommend that you generate the hash yourself with the contents of the HTTP Body, using your Client Secret as the hash key, and then compare it with the value received in the \"Body-Hash\" header to ensure that the request comes from a trusted source and has not been altered.

\n","auth":{"type":"noauth","isInherited":true,"source":{"_postman_id":"5a7f472f-5425-4d21-9fdf-53fdcb07cb4f","id":"5a7f472f-5425-4d21-9fdf-53fdcb07cb4f","name":"Your webhook","type":"folder"}},"urlObject":{"host":["{{Your_Webhook}}"],"query":[],"variable":[]}},"response":[{"id":"01a77f92-dfab-4bd4-86cd-0a2069fe6e12","name":"Get messages from Kiamo","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Body-Hash","value":"","description":"Hmac hash of the HTTP request body generated from the provided Client Secret, using the sha1 algorithm.","type":"text"},{"key":"Api-Version","value":"","description":"Kiamo API version number used to call your Webhook. This number will evolve with changes to the Kiamo.io Messaging API.","type":"text"}],"body":{"mode":"raw","raw":"{\n \"id\": \"1234546\",\n \"created_at\": 1676541889,\n \"customer_id\": \"customer_id_45465113\",\n \"sender\": {\n \"type\": \"human\",\n \"id\": \"kiamo\",\n \"name\": \"kiamo\"\n },\n \"body\": {\n \"message\": \"This is the textual content of the message transmitted by Kiamo, attachments are transmitted in the attachments property.\",\n \"attachments\": [\n {\n \"id\": \"abcdef1234567890\",\n \"name\": \"Attached image\",\n \"mime_type\": \"image/png\",\n \"content\": {\n \"type\": \"url\",\n \"data\": \"https://app.kiamo.io/messaging/attachments/xxxxxxxxxxx\"\n }\n }\n ]\n },\n \"metadata\": {\n \"foo\": \"bar\"\n }\n}","options":{"raw":{"headerFamily":"json","language":"json"}}},"url":{"raw":"https://app.kiamo.io/messaging/:client_webhook","protocol":"https","host":["app","kiamo","io"],"path":["messaging",":client_webhook"],"variable":[{"id":"5ef592f3-e2a8-4ed5-95db-67524b183f74","key":"client_webhook","value":""}]}},"status":"OK","code":200,"_postman_previewlanguage":"text","header":[],"cookie":[],"responseTime":null,"body":""}],"_postman_id":"8a57210e-f635-4d44-b98b-f9db3d8d7c86"}],"id":"5a7f472f-5425-4d21-9fdf-53fdcb07cb4f","auth":{"type":"noauth","isInherited":false},"event":[{"listen":"prerequest","script":{"id":"c03ddefb-26ea-4b1e-b9fc-4515dbb15cf0","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"cf03f309-ce5b-4aab-9913-dcf5d827a8a9","type":"text/javascript","exec":[""]}}],"_postman_id":"5a7f472f-5425-4d21-9fdf-53fdcb07cb4f","description":""},{"name":"/oauth2/v1/token","item":[{"name":"Create authentication token","id":"3d9bcb6b-1cac-45a8-aa92-8c6feac1594c","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"formdata","formdata":[{"key":"client_id","value":"YOUR_CLIENT_ID","description":"

The clientId given when your connector was created

\n","type":"text"},{"key":"client_secret","value":"YOUR_CLIENT_SECRET","description":"

The clientSecret given when your connector was created

\n","type":"text"},{"key":"grant_type","value":"client_credentials","type":"text"}]},"url":"https://app.kiamo.io/oauth2/v1/token","auth":{"type":"oauth2","oauth2":{"basicConfig":[],"advancedConfig":[{"key":"accessTokenUrl","value":""},{"key":"tokenName","value":""},{"key":"clientId","value":"YOUR_CLIENT_ID"},{"key":"clientSecret","value":"YOUR_CLIENT_SECRET"},{"key":"grant_type","value":""}]},"isInherited":true,"source":{"_postman_id":"aa67955b-a37e-4dc5-92ef-4bf2066f651f","id":"aa67955b-a37e-4dc5-92ef-4bf2066f651f","name":"Kiamo.io API Messaging / Bot","type":"collection"}},"urlObject":{"path":["oauth2","v1","token"],"host":["https://app.kiamo.io"],"query":[],"variable":[]}},"response":[{"id":"919b9636-c579-499e-91e0-c24175a80285","name":"Invalid Credentials","originalRequest":{"method":"POST","header":[],"body":{"mode":"formdata","formdata":[{"key":"client_id","value":"YOUR_CLIENT_ID","description":"The clientId given when your connector was created","type":"text"},{"key":"client_secret","value":"YOUR_CLIENT_SECRET","description":"The clientSecret given when your connector was created","type":"text"},{"key":"grant_type","value":"client_credentials","type":"text"}]},"url":"https://app.kiamo.io/oauth2/v1/token"},"status":"Unauthorized","code":401,"_postman_previewlanguage":"json","header":[{"key":"Date","value":"Thu, 20 Jul 2023 13:45:17 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"Cache-Control","value":"no-cache, private"},{"key":"Strict-Transport-Security","value":"max-age=15724800; includeSubDomains"}],"cookie":[],"responseTime":null,"body":"{\n \"error\": \"invalid_client\"\n}"},{"id":"f62578e0-e1ad-4d1b-b581-82d3c3300e01","name":"Token Creation Successfull","originalRequest":{"method":"POST","header":[],"body":{"mode":"formdata","formdata":[{"key":"client_id","value":"YOUR_CLIENT_ID","description":"The clientId given when your connector was created","type":"text"},{"key":"client_secret","value":"YOUR_CLIENT_SECRET","description":"The clientSecret given when your connector was created","type":"text"},{"key":"grant_type","value":"client_credentials","type":"text"}]},"url":"https://app.kiamo.io/oauth2/v1/token"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Date","value":"Thu, 20 Jul 2023 13:48:38 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"Cache-Control","value":"no-cache, private"},{"key":"Strict-Transport-Security","value":"max-age=15724800; includeSubDomains"}],"cookie":[],"responseTime":null,"body":"{\n \"access_token\": \"YOUR_ACCESS_TOKEN...\",\n \"expires_in\": 86400,\n \"token_type\": \"bearer\"\n}"}],"_postman_id":"3d9bcb6b-1cac-45a8-aa92-8c6feac1594c"}],"id":"9d0ef705-756e-4d22-b97c-ac808514b0f7","description":"

OAuth2.0 Authentication token

\n","_postman_id":"9d0ef705-756e-4d22-b97c-ac808514b0f7","auth":{"type":"oauth2","oauth2":{"basicConfig":[],"advancedConfig":[{"key":"accessTokenUrl","value":""},{"key":"tokenName","value":""},{"key":"clientId","value":"YOUR_CLIENT_ID"},{"key":"clientSecret","value":"YOUR_CLIENT_SECRET"},{"key":"grant_type","value":""}]},"isInherited":true,"source":{"_postman_id":"aa67955b-a37e-4dc5-92ef-4bf2066f651f","id":"aa67955b-a37e-4dc5-92ef-4bf2066f651f","name":"Kiamo.io API Messaging / Bot","type":"collection"}}},{"name":"/messaging/v1/messages","item":[{"name":"Send messages to Kiamo","id":"704d9a40-b161-4c16-8fd5-c5fc1e8d7dbe","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"},{"warning":"This is a duplicate header and will be overridden by the Authorization header generated by Postman.","key":"Authorization","value":"Bearer YOUR_ACCESS_TOKEN","type":"text"}],"body":{"mode":"raw","raw":"{\n \"messages\": [\n {\n \"id\": \"\",\n \"created_at\": 123456,\n \"customer_id\": \"\",\n \"sender\": {\n \"type\": \"human | bot\",\n \"id\": \"\",\n \"name\": \"\"\n },\n \"recipient\": {\n \"type\": \"human | bot\",\n \"id\": \"\",\n \"name\": \"\"\n },\n \"body\": {\n \"message\": \"\",\n \"attachments\": [\n {\n \"id\": \"\",\n \"name\": \"\",\n \"mime_type\": \"\",\n \"content\": {\n \"type\": \"url | base64\",\n \"data\": \"\"\n }\n }\n ],\n \"rich_content\": \"\"\n },\n \"metadata\": {\n \"key\": \"\"\n }\n }\n ]\n}","options":{"raw":{"headerFamily":"json","language":"json"}}},"url":"https://app.kiamo.io/messaging/v1/messages","description":"

Important!

customer_id must always be the unique identifier of the end customer from/to whom the message is sent. It is used by Kiamo to link the message to an existing interaction.
If you do not indicate a recipient it means that the message is for the Agent in Kiamo. Otherwise, it is a historical message exchanged between 2 interlocutors outside Kiamo.
Timestamps must be in standard UNIX format (number of seconds since january 1, 1970).

Conversation history

If you want to pass a conversation history between an end customer and your platform (for instance, a conversation between the customer and a chatbot), you need to pay attention to the following:

Send the complete conversation history in a single request when you need to transfer the conversation to an Agent in Kiamo.
In all messages, the customer_id must be the end customer's identifier (it will be used by Kiamo as a conversation identifier).
In each message, you must indicate a sender and a recipient.
The customer_id must match the sender.id for a message from the end customer; and must match the recipient.id for a message sent by your platform to the end customer.

A conversation history example is available in the examples provided

Responses

200 OK: Messages have been correctly recorded and will be forwarded to Kiamo.
\n
400 Bad request: Wrong format for query or body. Mandatory parameter missing or not compliant.
\n
401: Unauthorized access, your authentication token is invalid or expired.
\n
404: Resource not found, wrong url or object no longer exists.
\n
500: Internal Server Error.
\n

\n","auth":{"type":"oauth2","oauth2":{"basicConfig":[],"advancedConfig":[{"key":"accessTokenUrl","value":""},{"key":"tokenName","value":""},{"key":"clientId","value":"YOUR_CLIENT_ID"},{"key":"clientSecret","value":"YOUR_CLIENT_SECRET"},{"key":"grant_type","value":""}]},"isInherited":true,"source":{"_postman_id":"aa67955b-a37e-4dc5-92ef-4bf2066f651f","id":"aa67955b-a37e-4dc5-92ef-4bf2066f651f","name":"Kiamo.io API Messaging / Bot","type":"collection"}},"urlObject":{"path":["messaging","v1","messages"],"host":["https://app.kiamo.io"],"query":[],"variable":[]}},"response":[{"id":"2933939f-74bf-461f-993f-65754adcad34","name":"Send simple message","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"},{"key":"Authorization","value":"Bearer YOUR_ACCESS_TOKEN","type":"text"}],"body":{"mode":"raw","raw":"{\n \"messages\": [\n {\n \"id\": \"1234546\",\n \"created_at\": 1676541889,\n \"customer_id\": \"0601020304\",\n \"sender\": {\n \"type\": \"human\",\n \"id\": \"0601020304\",\n \"name\": \"John Doe\"\n },\n \"body\": {\n \"message\": \"Hello, I have a question. Can you help me?\"\n },\n \"metadata\": {}\n }\n ]\n}","options":{"raw":{"headerFamily":"json","language":"json"}}},"url":"https://app.kiamo.io/messaging/v1/messages"},"status":"OK","code":200,"_postman_previewlanguage":null,"header":null,"cookie":[],"responseTime":null,"body":null},{"id":"f359066f-26ca-47cc-b999-6930d5281ea2","name":"Chatbot conversation history","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"},{"key":"Authorization","value":"Bearer YOUR_ACCESS_TOKEN","type":"text"}],"body":{"mode":"raw","raw":"{\n \"messages\": [\n {\n \"id\": \"001\",\n \"created_at\": 1689755444,\n \"customer_id\": \"customer123\",\n \"sender\": {\n \"id\": \"customer123\",\n \"type\": \"human\",\n \"name\": \"M. John Doe\"\n },\n \"recipient\": {\n \"id\": \"chatbot456\",\n \"type\": \"bot\",\n \"name\": \"Chatbot Customer service\"\n },\n \"body\": {\n \"message\": \"Hello, I have a question about my order\"\n }\n },\n {\n \"id\": \"002\",\n \"created_at\": 1689755532,\n \"customer_id\": \"customer123\",\n \"sender\": {\n \"id\": \"chatbot456\",\n \"type\": \"bot\",\n \"name\": \"Chatbot Customer service\"\n },\n \"recipient\": {\n \"id\": \"customer123\",\n \"type\": \"human\",\n \"name\": \"M. John Doe\"\n },\n \"body\": {\n \"message\": \"Hello, How can I help?\\nYou need help to:\\n - Track your order\\n - Cancel your order\\n\"\n }\n },\n {\n \"id\": \"003\",\n \"created_at\": 1689755620,\n \"customer_id\": \"customer123\",\n \"sender\": {\n \"id\": \"customer123\",\n \"type\": \"human\",\n \"name\": \"M. John Doe\"\n },\n \"recipient\": {\n \"id\": \"chatbot456\",\n \"type\": \"bot\",\n \"name\": \"Chatbot Customer service\"\n },\n \"body\": {\n \"message\": \"It is about something else. I would like to cancel part of my order.\"\n }\n },\n {\n \"id\": \"004\",\n \"created_at\": 1689755681,\n \"customer_id\": \"customer123\",\n \"sender\": {\n \"id\": \"chatbot456\",\n \"type\": \"bot\",\n \"name\": \"Chatbot Customer service\"\n },\n \"recipient\": {\n \"id\": \"customer123\",\n \"type\": \"human\",\n \"name\": \"M. John Doe\"\n },\n \"body\": {\n \"message\": \"OK, I cannot do it but an adviser will help you.\"\n }\n }\n ]\n}","options":{"raw":{"headerFamily":"json","language":"json"}}},"url":"https://app.kiamo.io/messaging/v1/messages"},"_postman_previewlanguage":null,"header":null,"cookie":[],"responseTime":null,"body":null}],"_postman_id":"704d9a40-b161-4c16-8fd5-c5fc1e8d7dbe"}],"id":"aace67bc-9bb1-4c7e-8de6-95cf4208bf70","_postman_id":"aace67bc-9bb1-4c7e-8de6-95cf4208bf70","description":"","auth":{"type":"oauth2","oauth2":{"basicConfig":[],"advancedConfig":[{"key":"accessTokenUrl","value":""},{"key":"tokenName","value":""},{"key":"clientId","value":"YOUR_CLIENT_ID"},{"key":"clientSecret","value":"YOUR_CLIENT_SECRET"},{"key":"grant_type","value":""}]},"isInherited":true,"source":{"_postman_id":"aa67955b-a37e-4dc5-92ef-4bf2066f651f","id":"aa67955b-a37e-4dc5-92ef-4bf2066f651f","name":"Kiamo.io API Messaging / Bot","type":"collection"}}},{"name":"/messaging/attachments/{uid}/","item":[{"name":"Get attachment contents","id":"f7a8cc87-568e-40fe-bd7f-7827d106395c","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Accept","value":"application/octet-stream"},{"warning":"This is a duplicate header and will be overridden by the Authorization header generated by Postman.","key":"Authorization","value":"Bearer YOUR_ACCESS_TOKEN","type":"text"}],"url":"https://app.kiamo.io/messaging/attachments/{{Uid}}/","description":"

It is used to get the contents of an attachment.
The complete url of the attachment is sent to you in the content.data field of an attachment.
Once the attachment is retrieved, it is deleted from our servers, so be sure to save it.

Responses

200: The response body contains the binary stream of the attachment content. The Content-Type is the mime type of the attachment (e.g. image/png).
404: Resource not found, wrong url or object no longer exists.
500: Internal error.