Conversations API

Conversations over API is a platform for cross-channel communication where businesses can interact with their customers over a single API. You can integrate a custom range of Conversations (opens in a new tab) features to fulfill your needs:

• Supervisor dashboard
• Agent real-time communication interface
• Custom waiting strategy
• External bot integration such as welcome bot, mid-conversation bot, closing/satisfaction bot

Conversations HTTP API supports the following functionalities:

• Conversation threading
• Channels
• Agent, queues, and routing management
• Call center features

Depending on your business needs, you can use conversation threading only and skip the agent, queue, and routing management. However, if needed, you can also combine any of the functionalities mentioned above.

The solution also includes automated conversations over:

• Moments API (opens in a new tab)
• Moments using Flow on the web interface
• External bots (opens in a new tab)
• Broadcast messaging
• Customer data management and segmentation over People API (opens in a new tab), and People on the web interface.

You can find the technical specifications for the API integration in our Conversations API (opens in a new tab) documentation.

If you run into any issues, contact our Support (opens in a new tab) team.

Available channels

These are the supported channels over Conversations API:

• SMS
• WhatsApp
• Viber Business Messages
• Viber Bots
• Messenger
• RCS
• LINE
• Live Chat
• KakaoTalk
• Apple Messages for Business
• Instagram Messaging
• Telegram
• Email (Early Access)
• Calls (Voice and Video)

Webhooks

Webhooks are automated messages sent from one application to another when a specific event occurs. They enable real-time communication between systems by delivering data via HTTP requests.

Conversations webhooks provide instant access to conversation details and the latest message information, allowing you to manage customer inquiries more efficiently. They also enable real-time integrations to automate workflows for message routing, escalation, and analytics. As a result, they enhance operational reporting with comprehensive conversation and message-level metadata.

The following events are available:

1. Conversations created - Includes the unique MessageID and Last Message metadata for the first message of a conversation. This event occurs under the following circumstances:
   • A conversation is initiated by an inbound message (e.g., when a customer contacts the contact center, starting a new conversation).
   • An outbound conversation is started via web interface (e.g., when an agent begins a new conversation using the Start Conversation dialogue).
   • Customers utilize the CCAAS Public API to create an empty conversation (where there are no messages in the conversation initially).
2. Conversations status updated - The event occurs whenever the conversation status is updated, including statuses such as Open, Waiting, Solved, or Closed.
3. Conversations assignment updated - The event occurs whenever the assigned agent for a conversation is changed.
4. Message received - The event occurs whenever a new inbound message is received in a specific conversation.
5. Message updated - The event occurs whenever a message is updated.
6. Message deleted - The event occurs whenever a message is deleted.

MessageID and Last Message metadata are properties of the events listed above.

MessageID is a platform-wide unique identifier available for all supported events, while the Last Message metadata includes:

• Sender and recipient details
• Message direction (inbound/outbound)
• Message channel (e.g., WhatsApp, SMS, Email)

With these webhooks, you can receive notifications for incoming messages and conversational events through the Subscriptions management (opens in a new tab).

Check the tables below for more information about the events.

Conversation created

General event structure

Assignee

The Assignee model is designed as a composite JSON object to ensure its scalability and adaptability for future use.

Queue

The Queue model is designed as a composite JSON object to ensure its scalability and adaptability for future use.

Form

The Form model is designed as a composite JSON object to ensure its scalability and adaptability for future use.

Customer

The Customer model is designed as a composite JSON object to ensure its scalability and adaptability for future use.

Message data

The Last Message data includes metadata from the last message.

Example: Inbound conversation created from an inbound message

 
{
    "type": "CONVERSATION_CREATED",
    "payload":
    {
        "id": "ce83e955-1133-4adb-9847-47c83e6fc8bf",
        "status": "OPEN",
        "queue":
        {
            "id": "448bf76d-0047-49a3-93a4-ea8722d6aea9"
        },
        "priority": "URGENT",
        "channel": "WHATSAPP",
        "direction": "INBOUND",
        "assignee":
        {
            "id": null
        },
        "lastMessage":
        {
            "from": "givenCustomerNumber",
            "to": "givenAgentNumber",
            "channel": "WHATSAPP",
            "direction": "INBOUND"
        },
        "customer":
        {
            "id": "D12945086921DDDF4F36EBB3BE7AEFF1"
        },
        "form":
        {
            "id": "2cd74b30-3a06-4cfa-949a-77aa0d8cd17f"
        },
        "topic": null,
        "summary": null,
        "timestamp": "2023-06-20T16:44:24.572+00:00"
    }
}
 

Conversation status updated

General event structure

Message data

The Last Message data includes metadata from the last message.

Example: Conversation status changed to Closed

 
{
    "type": "CONVERSATION_STATUS_UPDATED",
    "payload":
    {
        "id": "ce83e955-1133-4adb-9847-47c83e6fc8bf",
        "status": "CLOSED",
        "lastMessage":
        {
            "from": "givenCustomerNumber",
            "to": "givenAgentNumber",
            "channel": "WHATSAPP",
            "direction": "INBOUND"
        },
        "timestamp": "2023-06-20T16:49:56.971+00:00"
    }
}
 

Conversation assignment updated

General event structure

Assignee

The Assignee model is designed as a composite JSON object to ensure its scalability and adaptability for future use.

Message data

The Last Message data includes metadata from the last message.

Example: Conversation assignment changed event

 
{
    "type": "CONVERSATION_ASSIGNMENT_UPDATED",
    "payload":
    {
        "id": "ce83e955-1133-4adb-9847-47c83e6fc8bf",
        "assignee":
        {
            "id": "FBCFE58EA5C33A80B569F631DBB27C41"
        },
        "lastMessage":
        {
            "from": "givenCustomerNumber",
            "to": "givenAgentNumber",
            "channel": "WHATSAPP",
            "direction": "INBOUND"
        },
        "timestamp": "2023-06-20T16:45:39.138+00:00"
    }
}
 

Message received

Root element

The INBOUND_MESSAGE event includes both message and authentication parameters, with authentication containing Live Chat (opens in a new tab) authentication details.

Message

Authentication

Example: WhatsApp text message

 
{
  "type": "INBOUND_MESSAGE",
  "payload": {
    "message": {
      "id": "bb88179a-76c0-4f7b-b076-852c53e8b646",
      "channel": "WHATSAPP",
      "from": "385989674681",
      "to": "447860064529",
      "conversationId": "6ec0d737-e066-450e-a435-f2b77cd8bbe3",
      "createdAt": "2023-06-18T13:12:36.581+00:00",
      "updatedAt": "2023-06-18T13:12:36.581+00:00",
      "content": {
        "text": "Hi",
        "context": null,
        "referral": null,
        "type": "TEXT"
      }
    },
    "authentication": null
  }
}
 

Message updated

Root element

The event includes message and authentication parameters, with authentication carrying Live Chat (opens in a new tab) authentication parameters.

Message

Example: Facebook Post text message

 
{
    "type": "INBOUND_MESSAGE_UPDATED",
    "payload":
    {
        "message":
        {
            "id": "bb88179a-76c0-4f7b-b076-852c53e8b646",
            "messageid": "bb88179a-76c0-4f7b-b076-852c53e8b646",
            "channel": "FACEBOOK_POST",
            "from": "givenFacebookPostCustomerNumber",
            "to": "givenFacebookPostAgentNumber",
            "conversationId": "6ec0d737-e066-450e-a435-f2b77cd8bbe3",
            "createdAt": "2023-06-18T13:12:36.581+00:00",
            "updatedAt": "2023-06-18T13:12:36.581+00:00",
            "content":
            {
                "text": "Hi",
                "context": null,
                "referral": null,
                "type": "TEXT"
            }
        },
        "authentication": null
    }
}
 

Message deleted

Root element

The event includes message and authentication parameters, with authentication carrying Live Chat (opens in a new tab) authentication parameters.

Message

Example: Facebook Post text message

 
{
    "type": "INBOUND_MESSAGE_DELETED",
    "payload":
    {
        "message":
        {
            "id": "bb88179a-76c0-4f7b-b076-852c53e8b646",
            "messageid": "bb88179a-76c0-4f7b-b076-852c53e8b646",
            "channel": "FACEBOOK_POST",
            "from": "givenFacebookPostCustomerNumber",
            "to": "givenFacebookPostAgentNumber",
            "conversationId": "6ec0d737-e066-450e-a435-f2b77cd8bbe3",
            "createdAt": "2023-06-18T13:12:36.581+00:00",
            "updatedAt": "2023-06-18T13:12:36.581+00:00",
            "content":
            {
                "text": "Hi",
                "context": null,
                "referral": null,
                "type": "TEXT"
            }
        },
        "authentication": null
    }
}