The Messages API is part of Voiso's Conversations APIs. It can be used to retrieve the message content of specific conversations from digital channels such as WhatsApp, Viber, WebChat, Telegram, and so on.
Please refer to the detailed API endpoint specification here.
The Messages API requires the base URL and the user API key.
The Messages API uses the following parameters.
The Authorization: Bearer token parameter is the user API key. It is used in the request header.
| Parameter | Description | Type | Required | Notes |
|---|---|---|---|---|
| uuid | The unique identifier of the conversation. | string | Required | Tip: Use the CDR API to retrieve conversation UUIDs. |
| offset | The number of messages in the conversation to skip before collecting messages for the request. | string | Optional | Tip: Use this parameter to skip system and bot messages. |
| limit | The number of messages to retrieve in a single request. | string | Optional |
With the requried parameters, you can make a simple request:
{
"method": "GET",
"url": "https://cluster1.voiso.com/api/conversation/v1/conversations/45afb076-ae74-4fbf-baa7-2d81bef2d969/messages",
"headers": {
"Authorization": "Bearer 8a7b2c9d3e4f5g6h7i8j9k0l1m2n3o4p5q6r7s8t9u0v1w2x",
"Accept": "application/json"
}
}
With the optional parameters, you can make a more targeted request:
{
"method": "GET",
"url": "https://cluster1.voiso.com/api/conversation/v1/conversations/45afb076-ae74-4fbf-baa7-2d81bef2d969/messages",
"headers": {
"Authorization": "Bearer 8a7b2c9d3e4f5g6h7i8j9k0l1m2n3o4p5q6r7s8t9u0v1w2x",
"Accept": "application/json"
}
}
The following table describes the elements of the response.
| Element | Sub-element | Sub-sub-element | Description | Type | Notes |
|---|---|---|---|---|---|
| Messages | A list of omnichannel messages that are part of a conversation. | object | |||
| id | A unique identifier for a single message in a conversation. | string | |||
| conversation_id | A unique identifier for all the messages that are part of the same conversation. | string | |||
| content_type | The data type for the message. Refer to the Content type table below. | string | Content type is dependent on the channel type. Possible values are: text, image, document, audio, video, voice, contact, location, and template | ||
| content_data | Either the text of a message or the metadata for an attachment. | object | |||
| text | The body of a single text message in a conversation. | string | |||
| size | For attachments, the size of the attachment file. | string | In bytes. | ||
| caption | For attachments, the message body included with the attachment. | string | |||
| filename | For attachments, the name of the attached file. | string | |||
| URL | For attachments, the location of the file. | string | |||
| id | For WhatsApp templates, the UUID assigned to the template. | string | |||
| body | For WhatsApp templates, the message content in the template. | string | |||
| language | For WhatsApp templates, the two-letter language code indicating the language of the message content.. | string | |||
| components | For WhatsApp templates, the structural components of a WhatsApp template, such as quick responses, calls to action, and URLs. | object | |||
| whatsapp_template_id | For WhatsApp templates, the name of the template. | string | |||
| activity | The type of activity represented by the message. | string | Possible values are: message and event. | ||
| activity_type | This includes interaction events. | string | Activity types are dependent on the channel type. Possible values are: inbound, outbound, whisper, accept, forward_to_queue, accept_forwarding, intercept, archive, terminate, disconnect, start_monitoring, stop_monitoring, start_whispering, stop_whispering, start_barging_in, stop_barging_in, business_initiated_wait, and force_close | ||
| participant | An array of metadata describing one of the parties in the conversation. | object | |||
| id | number | An identifier assigned to the participant. Participants can be contacts, agents, and bots (system messages). The value null is used for bots and events. | |||
| type | There are three basic types, agent, supervisor, and contact. The agent type also includes bots. | string | |||
| attributes | Reserved for future use. | object | |||
| status | The current state of the message. Refer to the Status table below. | string | Status is dependent on the channel type. Possible values are: sent, delivered, seen, deleted, and failed. | ||
| updated_at | The date and time that the message was last modified. | string | Date and time are in the following format: YYYY-MM-DDThh:mm:ss.sssZ | ||
| created_at | The date and time that the message was first created. | string | Date and time are in the following format: YYYY-MM-DDThh:mm:ss.sssZ | ||
| metadata | Information about the request settings and response content. | object | |||
| limit | The value set for the number of number of conversations to be returned. | number | |||
| offset | The value set for the number of messages in the conversation to skip. | number | |||
| total | The number of conversations returned in the response. | number |
| Channel | content_type |
|---|---|
| text, image, document | |
| text, image | |
| Telegram | text, image, document, audio, video |
| Viber | text, image, document |
| Webchat | text, document, notification |
| text, image, document, audio, video, template |
| Channel | status |
|---|---|
| initial, accepted, waiting, ready, sent, delivered, seen, failed | |
| initial, accepted, waiting, ready, sent, delivered, seen, failed | |
| Telegram | initial, accepted, waiting, ready, sent, failed |
| Viber | initial, accepted, waiting, ready, sent, delivered, seen, failed |
| Webchat | initial, accepted, waiting, ready, sent, delivered, seen, failed |
| initial, accepted, waiting, ready, sent, delivered, seen, deleted, failed |
{
"messages": [
{
"id": 345f1cdc-1e70-45b8-878c-376f9fa1a2d1,
"conversation_id": "70e8de7f-3d98-4af0-9315-9d2dff75745d",
"content_type": "text",
"content_data": {
"text": "Welcome to Voiso"
},
"activity": "message",
"activity_type": "outbound",
"participant": {
"id": 77572,
"type": "agent"
},
"attributes": {},
"status": "seen",
"updated_at": "2023-09-12T11:29:38.642Z",
"created_at": "2023-09-12T11:29:38.000Z"
}
],
"metadata": {
"limit": 1,
"offset": 0,
"total": 1
}
}
The following is a sample response for a Webchat interaction that includes an attached PNG file.
{
"messages": [
{
"id": "345f1cdc-1e70-45b8-878c-376f9fa1a2d1",
"conversation_id": "9ba5cd12-e248-4b89-b7f2-d354a6c5a8ef",
"content_type": "text",
"content_data": {
"text": "Hello, I am interested in learning about your travel destinations."
},
"activity": "message",
"activity_type": "inbound",
"participant": {
"id": 42075,
"type": "contact"
},
"attributes": {},
"status": "seen",
"updated_at": "2024-05-17T16:34:52.494Z",
"created_at": "2024-05-17T16:34:52.456Z"
},
{
"id": "aecef3b7-ccf6-4895-b38b-3923c168ee52",
"conversation_id": "9ba5cd12-e248-4b89-b7f2-d354a6c5a8ef",
"content_type": "text",
"content_data": {
"text": "Greetings,\n\nThank you for reaching out to us! We are currently seeking a dedicated agent to provide you with assistance."
},
"activity": "message",
"activity_type": "outbound",
"participant": {
"id": null,
"type": "agent"
},
"attributes": {},
"status": "seen",
"updated_at": "2024-05-17T16:35:02.304Z",
"created_at": "2024-05-17T16:34:52.533Z"
},
{
"id": "ad7f2388-a8ee-4334-b36d-6b31ed915acc",
"conversation_id": "9ba5cd12-e248-4b89-b7f2-d354a6c5a8ef",
"content_type": "",
"content_data": {},
"activity": "event",
"activity_type": "accept",
"participant": {
"id": 226,
"type": "agent"
},
"attributes": {},
"status": null,
"updated_at": "2024-05-17T16:35:03.000Z",
"created_at": "2024-05-17T16:35:03.000Z"
},
{
"id": "c77f8625-8081-4ef1-8a5f-1d4f869d6b6d",
"conversation_id": "9ba5cd12-e248-4b89-b7f2-d354a6c5a8ef",
"content_type": "text",
"content_data": {
"text": "Of course! Are you interested in a particular region?"
},
"activity": "message",
"activity_type": "outbound",
"participant": {
"id": 226,
"type": "agent"
},
"attributes": {},
"status": "seen",
"updated_at": "2024-05-17T16:37:46.418Z",
"created_at": "2024-05-17T16:37:46.393Z"
},
{
"id": "9cf3facb-28f5-4721-8d1b-fdfdbef63988",
"conversation_id": "9ba5cd12-e248-4b89-b7f2-d354a6c5a8ef",
"content_type": "text",
"content_data": {
"text": "Europe or North Africa"
},
"activity": "message",
"activity_type": "inbound",
"participant": {
"id": 42075,
"type": "contact"
},
"attributes": {},
"status": "seen",
"updated_at": "2024-05-17T16:38:12.878Z",
"created_at": "2024-05-17T16:38:12.867Z"
},
{
"id": "09b2c38c-e446-477d-8eab-7f9191aed1c6",
"conversation_id": "9ba5cd12-e248-4b89-b7f2-d354a6c5a8ef",
"content_type": "text",
"content_data": {
"text": "We have a special on Greece this week!"
},
"activity": "message",
"activity_type": "outbound",
"participant": {
"id": 226,
"type": "agent"
},
"attributes": {},
"status": "seen",
"updated_at": "2024-05-17T16:39:59.447Z",
"created_at": "2024-05-17T16:39:59.406Z"
},
{
"id": "745d4c77-7d8b-4edf-b69f-0407bf6aef45",
"conversation_id": "9ba5cd12-e248-4b89-b7f2-d354a6c5a8ef",
"content_type": "text",
"content_data": {
"text": "Perfect! Can you send me the details?"
},
"activity": "message",
"activity_type": "inbound",
"participant": {
"id": 42075,
"type": "contact"
},
"attributes": {},
"status": "seen",
"updated_at": "2024-05-17T16:46:10.741Z",
"created_at": "2024-05-17T16:46:10.735Z"
},
{
"id": "c1239b8d-f542-4c39-8691-2d3788be1bdd",
"conversation_id": "9ba5cd12-e248-4b89-b7f2-d354a6c5a8ef",
"content_type": "image",
"content_data": {
"size": 78915,
"caption": "Here they are!",
"filename": "GreecePromo.png",
"url": "https://cluster1.voiso.com/omni/media/eyJhbGciOiJIUzI1NiJ9.eyJrZXkiOiIyMDI0LzA1LzE3LzY4ZDczNmYzLTUyNTUtNDRjOC1hZDUwLTg3M2I4MmQ2ZDI1YSIsImV4cCI6MTcxOTI0NDQxOH0.Qf0yoXH1Wr4F_BTWmCM6yvpMQTktrhW6Pi7UlD_a3k4/GreecePromo.png"
},
"activity": "message",
"activity_type": "outbound",
"participant": {
"id": 226,
"type": "agent"
},
"attributes": {},
"status": "seen",
"updated_at": "2024-05-17T16:46:54.559Z",
"created_at": "2024-05-17T16:46:54.532Z"
},
{
"id": "a8bd1e45-b20e-4ad0-9e64-1db3557167e0",
"conversation_id": "9ba5cd12-e248-4b89-b7f2-d354a6c5a8ef",
"content_type": "",
"content_data": {},
"activity": "event",
"activity_type": "disconnect",
"participant": {
"id": null,
"type": "agent"
},
"attributes": {},
"status": null,
"updated_at": "2024-05-17T18:08:29.000Z",
"created_at": "2024-05-17T18:08:29.000Z"
}
],
"metadata": {
"limit": 25,
"offset": 0,
"total": 9
}
}
The following issues are sometimes encountered:
If you see this error, "error": "Conversation not found", a conversation with the specified UUID could not be found. Use the CDR API to verify that the UUID is correct.
The Messages API uses the contact center API key to validate the request. If you see this error, "error": "Invalid API key", check that you use the correct contact center API key. For more information about API keys, refer to Authentication.
If you see this error, "error": "Specified parameters are not valid", check syntax of the parameters in the request.
If you see this error, "error": "No access to API", the user does not have the correct permissions set in their access group.
Was this page helpful?