Please refer to the detailed API endpoint specification: Get conversation messages

Purpose

This API lets you query the CDR for the content of Digital Channels messages Get conversation messages requests to your contact center.

Prerequisites

The UUID of the conversation. Use the List CDRs to retrieve UUIDs.
The user must have the following permissions granted to their account:
- View all CDRs
- View team CDRs
- View call events

Making requests

Authentication

The Messages API requires the Base URL and the API key of a specific user.

Request parameters

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 List CDRs 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 required parameters, you can make a simple request:

{
  "method": "GET",
  "url": "https://cluster1.contact_center_name.com/api/conversation/v1/conversations/45afb076-ae74-4fbf-baa7-2d81bef2d969/messages",
  "headers": {
    "Authorization": "Bearer 8a7b2c9d3e4f5g6h7i8j9k0l1m2n3o4p5q6r7s8t9u0v1w2x",
    "Content-Type": "application/json"
  }
}

With the optional parameters, you can make a more targeted request:

GET
https://cluster1.contact_center_name.com/api/conversation/v1/conversations/45afb076-ae74-4fbf-baa7-2d81bef2d969/messages?offset=100&limit=50

Authorization: Bearer 8a7b2c9d3e4f5g6h7i8j9k0l1m2n3o4p5q6r7s8t9u0v1w2x
Content-Type: application/json

Response

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

Content type

Channel	content_type
Facebook	text, image, document
Instagram	text, image
Telegram	text, image, document, audio, video
Viber	text, image, document
Webchat	text, document, notification
WhatsApp	text, image, document, audio, video, template

Status

Channel	status
Facebook	initial, accepted, waiting, ready, sent, delivered, seen, failed
Instagram	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
WhatsApp	initial, accepted, waiting, ready, sent, delivered, seen, deleted, failed

Sample response (simple)

{
  "messages": [
    {
      "id": 345f1cdc-1e70-45b8-878c-376f9fa1a2d1,
      "conversation_id": "70e8de7f-3d98-4af0-9315-9d2dff75745d",
      "content_type": "text",
      "content_data": {
        "text": "Welcome to Contact_Center_Name"
      },
      "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
  }
}

Sample response (Webchat)

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.contact_center_name.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
    }
}

Troubleshooting

The following issues are sometimes encountered:

Conversation not found

If you see this error, "error": "Conversation not found", a conversation with the specified UUID could not be found. Use the List CDRs to verify that the UUID is correct.

Authorization error

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.

Validation error

If you see this error, "error": "Specified parameters are not valid", check syntax of the parameters in the request.

Forbidden error

If you see this error, "error": "No access to API", the user does not have the correct permissions set in their access group.