Conversations over API

Conversations HTTP API supports the following functionalities:

  • Conversation threading
  • Channels: SMS, WhatsApp, Viber, Facebook Messenger, RCS, Line and Live Chat
  • Agent, queues, and routing management

You can use the conversation threading only and skip the agent, queue, and routing management. Additionally, you can combine the ones you need.

The solution also includes automated conversations over Flow API or Flow module on web interface or external bots, Broadcast messaging and customer data management and segmentation over People API, or People on web interface.

Technical details for the API integration can be found on our Conversations article on the Infobip API Developer Hub.

Create Conversation

A conversation is a container for messages exchanged between agents and the customer. The conversations have the following descriptions: topic, summary, status, priority, queue, agent, and channel.

All parameters are optional. Parameters status, priority and channel will get default values if not provided.

Refer to the how to create a conversation on our Infobip API Developer Hub.

Property

name

Type

Description

topic

string

The topic of conversation, can be any text up to 255 characters.

summary

string

Short description of conversation, can be any text up to 255 characters.

status

string

Conversation status (open, solved, closed). If no status is provided, will be set to default: open.

priority

string

Conversation priority (URGENT, HIGH, NORMAL, LOW). If no priority is provided, will be set to default: NORMAL

queueId

string

Queue id that conversation belongs to

agentId

string

Agent id assigned to the conversation

channel

string

Communication channel (SMS, VIBER,
WHATSAPP, FACEBOOK_MESSENGER, MULTICHANNEL, NO_CHANNEL). If no CHANNEL is provided, will be set to default: NO_CHANNEL

Update Conversation

Any conversation property can be updated until a conversation is marked as Closed.

Get Conversations

Use this method to get a list of conversations based on the desired criteria with pagination and filtering options. Results can be filtered by one or many optional filters described in the parameters table below.

Parameters

Property name

Type

Description

conversationIds

array of strings

Optional filter. List of conversation Ids to match result.

queueIds

array of strings

Optional filter. List of queue Ids to match result.

agentId

string

Optional filter. List of agent Ids to match result.

status

string

Optional filter. Match any of status with result. Possible values: OPEN, WAITING, SOLVED, CLOSED.

priority

string

Optional filter. Match any of priority with result. Possible values: URGENT, HIGH, NORMAL, LOW.

tagNames

array of strings

Optional filter. List of tag names to match result.

createdAfter

datetime

Optional filter. Filter result with created after dateTime. Format: yyyy-MM-dd'T'HH:mm:ss.SSSZ

createdBefore

datetime

Optional filter. Filter result with created before dateTime. Format: yyyy-MM-dd'T'HH:mm:ss.SSSZ

updatedAfter

datetime

Optional filter. Filter result with created after dateTime. Format: yyyy-MM-dd'T'HH:mm:ss.SSSZ

updatedBefore

datetime

Optional filter. Filter result with created before dateTime. Format: yyyy-MM-dd'T'HH:mm:ss.SSSZ

limit

integer

Size of the result page. If a limit count is given, no more than that many rows will be returned (but possibly less, if the query itself yields fewer rows). The default value is 10, the max value is 999.

page

integer

This parameter says to skip that many rows before beginning to return rows. If both page and limit appear, then page rows are skipped before starting to count the limit rows that are returned. The default value is 0.

orderBy

string

This parameter is used to order your results. If an order is not given, the default order of asc will be applied. Possible ordering fields are properties. Ordering direction can be specified with modifiers asc for the ascending order or desc for the descending one.

Request example

{
    "conversations": [
        {
            "id": "37B93F4D2BA3C58B58526EAEAA1AB35C",
            "topic": "Conversation demo topic",
            "summary": null,
            "status": "OPEN",
            "priority": "NORMAL",
            "queueId": null,
            "agentId": null,
            "createdAt": "2019-04-24T11:25:41.058+0000",
            "updatedAt": "2019-04-24T11:25:41.058+0000",
            "channel": "NO_CHANNEL"
        },
        {
            "id": "9F1F21C198025CC026956A7E2E9C560F",
            "topic": "API help",
            "summary": "API not working properly",
            "status": "OPEN",
            "priority": "HIGH",
            "queueId": "FBDDA7F8B33417374ACC02F5265527E6",
            "agentId": "F66D67327326FCCB027BEAA916B94542",
            "createdAt": "2019-04-24T11:25:41.058+0000",
            "updatedAt": "2019-04-24T11:25:41.058+0000",
            "channel": "SMS"
        }
    ],
    "pagination": {
        "totalItems": 2,
        "page": 0,
        "limit": 10,
        "orderBy": "id:ASC"
    }
}

Add Tag to Conversation and Remove Tag from Conversation

With Add or Remove Tag methods you can categorize conversations for assignment or reporting purposes. The only mandatory parameter is the conversationId and the tag name. Removing the tag from the conversation doesn't delete the tag nor the conversation.

Route Conversation

With this method you can set a conversation to unassigned and initiate the routing process again. This is typically used to manage transferring conversations from a bot to agent. You can create bots with the Infobip Flow or connect an external bot. Find more details regarding the how to connect external bot setup.

Conversations with the closed status cannot be routed. Read more on the routing process.

Messages

Create Message

Inbound messages are automatically threaded if the channels and senders are configured for conversation threading. To add outbound messages to a conversation, use this method to send a message via any of the supported channels.

Property name

Type

Description

conversationId

string

Required - Conversation Id to set message to

from

string

Required - Agent telephone number message is sent from

to

string

Required - Destination, customer telephone number message is sent to

channel

string

Required - Selected channel to send the message (SMS, VIBER, WHATSAPP, FACEBOOK_MESSENGER, RCS, LINE, LIVE_CHAT)

content

string

Required - Content of message can be any text up to 4000 characters. Content limits are channel dependent. More information on Long SMS.

Get Messages

To fetch all messages exchanged in a conversation, use the get messages method.

Notes

Use notes to notify your team on important matters concerning a conversation with a customer. Below are the methods for Notes management:

Tags

Tags can be assigned to the conversations to categorize them into topics or customer intents. Tags can be created ad hoc over the create tag method or automatically within journey automation flow when a conversation is transferred to Agents.

Parameters:

Property name

Type

Description

name

string

Required - Tag name content can be any text up to 4000 characters.

DUPLICATE TAG

If you try to create a tag with a name that already exists in the system, you will get the following response: “STATUSCODE”: “ERROR”, “MESSAGE”: “TAG ALREADY EXISTS”

Available tag management methods are listed below:

Create Tag

With this method you can create new tags. Only the tag name is required.

Delete Tag

Tags can be deleted at any point in time with the Delete tag method.

DELETE TAG

Deleting a tag will remove the tag from all associated conversations. This operation cannot be reverted.

Get Tags

With this method, you can retrieve list of all tags under your account or for a specific conversationId.