Messages

API Docs by APIMATIC
API OverviewConversations

Messages
#

Messages
#

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.

Prerequisites
#

  • The UUID of the conversation. Use the CDR API 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 user API key.

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.

ParameterDescriptionTypeRequiredNotes
uuidThe unique identifier of the conversation.stringRequiredTip: Use the CDR API to retrieve conversation UUIDs.
offsetThe number of messages in the conversation to skip before collecting messages for the request.stringOptionalTip: Use this parameter to skip system and bot messages.
limitThe number of messages to retrieve in a single request.stringOptional

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"
  }
}

Response
#

The following table describes the elements of the response.

ElementSub-elementSub-sub-elementDescriptionTypeNotes
MessagesA list of omnichannel messages that are part of a conversation.object
idA unique identifier for a single message in a conversation.string
conversation_idA unique identifier for all the messages that are part of the same conversation.string
content_typeThe data type for the message. Refer to the Content type table below.stringContent type is dependent on the channel type. Possible values are: text, image, document, audio, video, voice, contact, location, and template
content_dataEither the text of a message or the metadata for an attachment.object
textThe body of a single text message in a conversation.string
sizeFor attachments, the size of the attachment file.stringIn bytes.
captionFor attachments, the message body included with the attachment.string
filenameFor attachments, the name of the attached file.string
URLFor attachments, the location of the file.string
idFor WhatsApp templates, the UUID assigned to the template.string
bodyFor WhatsApp templates, the message content in the template.string
languageFor WhatsApp templates, the two-letter language code indicating the language of the message content..string
componentsFor WhatsApp templates, the structural components of a WhatsApp template, such as quick responses, calls to action, and URLs.object
whatsapp_template_idFor WhatsApp templates, the name of the template.string
activityThe type of activity represented by the message.stringPossible values are: message and event.
activity_typeThis includes interaction events.stringActivity 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
participantAn array of metadata describing one of the parties in the conversation.object
idnumberAn identifier assigned to the participant. Participants can be contacts, agents, and bots (system messages). The value null is used for bots and events.
typeThere are three basic types, agent, supervisor, and contact. The agent type also includes bots.string
attributesReserved for future use.object
statusThe current state of the message. Refer to the Status table below.stringStatus is dependent on the channel type. Possible values are: sent, delivered, seen, deleted, and failed.
updated_atThe date and time that the message was last modified.stringDate and time are in the following format: YYYY-MM-DDThh:mm:ss.sssZ
created_atThe date and time that the message was first created.stringDate and time are in the following format: YYYY-MM-DDThh:mm:ss.sssZ
metadataInformation about the request settings and response content.object
limitThe value set for the number of number of conversations to be returned.number
offsetThe value set for the number of messages in the conversation to skip.number
totalThe number of conversations returned in the response.number

Content type
#

Channelcontent_type
Facebooktext, image, document
Instagramtext, image
Telegramtext, image, document, audio, video
Vibertext, image, document
Webchattext, document, notification
WhatsApptext, image, document, audio, video, template

Status
#

Channelstatus
Facebookinitial, accepted, waiting, ready, sent, delivered, seen, failed
Instagraminitial, accepted, waiting, ready, sent, delivered, seen, failed
Telegraminitial, accepted, waiting, ready, sent, failed
Viberinitial, accepted, waiting, ready, sent, delivered, seen, failed
Webchatinitial, accepted, waiting, ready, sent, delivered, seen, failed
WhatsAppinitial, 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 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
  }
}

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

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 CDR API 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.


Was this page helpful?

Thank you! Your feedback has been received.