Skip to main content

Operator API

tip
The Operator API is a REST API that can be used to integrate customer engagement platforms with Tovie DialogStudio.

You can use the Operator API to connect any customer engagement platform to the chatbot project created on Tovie DialogStudio. When the customer engagement platform is integrated with Tovie DialogStudio, data received by the chatbot during the conversation with the client is sent to the application.

You can use API methods to:

  • send a message or a file link to the agent;
  • choose a group of agents to process requests;
  • pass additional client information to the agent;
  • subscribe to notifications about:
    • new messages;
    • delivery of client messages;
    • messages closed by the agent.

API methods

For Operator API integration, you will need to create a web server that supports the following methods:

caution
All Operator API requests include {apiUrl} — the full URL of web server you are going to send requests to.

POST /setWebhook

The method sets the webhook where events will be routed to be processed by Tovie DialogStudio. For instance, sending a message processed by the agent or closing the chat.

Request

POST {apiUrl}/setWebhook

Request body

{
"url": "http://{host_name}/chatadapter/chatapi/webhook/operatorapi/{apiKey}",
}

Request parameters

ParameterTypeDescription
apiUrlstringAPI URL where Operator API requests will be routed to.
urlstringThe webhook set by the setWebhook method. It will later be used to accept events routed to Tovie DialogStudio.
ApiKeystringChannel ID.

POST /sendText

The client sent a message to the chat with the agent.

Request

POST {apiUrl}/sendText

Request body

{
"userId": "<userId>",
"text": "text"
}

Request parameters

ParameterTypeMandatoryDescription
userIdstringYesClient ID.
textstringYesText message sent by the client.

POST /sendFile

The client sent a file to the chat with the agent.

Request

POST {apiUrl}/sendFile

Request body

{
"userId": "<userId>",
"url": "http://someUrl",
"fileName": "example",
"size": 1
}

Request parameters

ParameterTypeMandatoryDescription
userIdstringYesClient ID.
urlstringYesFile download link.
fileNamestringNoName of the file to be downloaded.
sizeintegerNoFile size in bytes.

POST /closeChat

The client closed the chat with the agent.

Request

POST {apiUrl}/closeChat

Request body

{
"userId": "<userId>",
"text": "The user closed the dialog"
}

Request parameters

ParameterTypeMandatoryDescription
userIdstringYesClient ID.
textstringYesText message sent when the chat was closed.

POST /selectDestination

The method creates a session between the chatbot client and the selected agent.

Request

POST {apiUrl}/selectDestination

Request body

{
"userId":"<userId>",
"destinationId":"54321",
"userName":"firstName lastName",
"attributes":{
"key1":"value1",
"key2":"value2"
},
"hiddenAttributes":{
"key1":"value1",
"key2":"value2"
},
"customData":{

}
}

Request parameters

ParameterTypeMandatoryDescription
userIdstringYesClient ID assigned on the Tovie DialogStudio platform.
destinationIdstringYesAgent ID assigned by the agent application.
userNamestringNoThe client’s first name. If no value is passed, the agent will see {channel} {userId} as the name.
attributesstringNoPre-chat field.
Accepts JSON in the {"key":"value"} form.
Parameters will be passed to the agent as additional client information.
hiddenAttributesstringNoPre-chat field that will not be sent to the agent.
The format is similar to attributes.
customDatastringNoAdditional data to be switched to the agent.

GET /getDestinations

The method gets available agent groups to route events to.

Request

GET {apiUrl}/getDestinations

Answer

{
"destinations":[
{
"destinationId":"1",
"name":"Agent group 1",
"hasOnline":true
},
{
"destinationId":"2",
"name":"Agent group 2",
"hasOnline":false
}
]
}

Response format

ParameterTypeDescription
destinationIdstringAgent group ID.
namestringAgent group name.
hasOnlinebooleanAgent group availability for event routing.

Passing events to Tovie DialogStudio

tip
A webhook is set for a POST {apiUrl}/setWebhookrequest where events from agents should be routed to.

Webhook format

http://{host_name}/chatadapter/chatapi/webhook/operatorapi/{apiKey}

Request

POST ​/chatapi​/webhook​/operatorapi​/{apiKey}

Request body

The request body contains the data required to create or modify an object. The data must be in JSON format.

You can see the events that can be sent, their structure, and the fields below.

Show the details
Request body: TextMessage | FileMessage | Closed

TextMessage: {
"id": "id",
"userId": "54321",
"type": "TextMessage",
"text": "text",
"employee": {
"employeeId": "id",
"firstName": "first name",
"lastName": "last name",
"avatarUrl": "http://someUrl",
},
},

FileMessage {
"id": "id",
"userId": "54321",
"type": "FileMessage",
"url": "http://someUrl",
"employee": {
"employeeId": "id",
"firstName": "first name",
"lastName": "last name",
"avatarUrl": "http://someUrl",
},
"name": "example",
"size": "2",
"comment": "file",
},

Closed {
"id": "id",
"userId": "54321",
"type": "Closed",
"employee": {
"employeeId": "id",
"firstName": "first name",
"lastName": "last name",
"avatarUrl": "http://someUrl",
},
},

SelectDestination {
"id": "id",
"userId": "54321",
"type": "SelectDestination",
"destination": {
"destinationId": "id",
"name": "name",
"hasOnline": "true",
},
}

Event types

EventDescription
TextMessageText message from the agent.
FileMessageAttached file from the agent.
ClosedMessage closed by the agent.
SelectDestinationSelected routing destination.

Request parameters

ParameterTypeMandatoryDescription
idstringYesMessage identifier.
userIdstringYesClient ID.
typestringYesEvent type.
Employee
employeeIdstringYesAgent ID.
firstNamestringYesAgent first name.
lastNamestringYesAgent last name.
avatarUrlstringYesLink to the avatar of the agent.
TextMessage
textstringYesText message sent by the agent.
FileMessage
urlstringYesFile download link.
namestringYesName of the file to be downloaded.
sizeintegerYesFile size in bytes.
commentstringYesComment to the file being sent.
SelectDestination
destinationIdstringYesAgent group ID.
namestringYesAgent group name.
hasOnlinebooleanYesAgent group availability for event routing.

Connect the channel

Sign in to Tovie DialogStudio and go to your project. Click Channels > Transfer to the agent in the control panel. Select the channel for Operator API connection.

Fill out the following fields:

  • Channel name — specify the channel name.
  • API URL — the URL where Operator API requests will be routed to.

When you use the Operator API channel, you can transfer the dialog not only to the particular agent, but also to the agent group. In this case, the dialog will be assigned to one of the agents from the group you’ve specified.

To add the agent group, press the Add group button and fill out the following fields:

  • Channel name — specify the name for the agent group.
  • Description — add the description for the agent group.
  • Ids — from the drop-down list, choose the identifier of the agent group that exists in the online chat platform you use.

You can add more agent groups in the same way.

To delete the agent group, use the  button in the upper right corner of the group you’ve added.

Click Connect.

Transfer to agent

To switch the dialog from the bot to the agent, you need to add the Transfer to agent block to the script. The cases where the bot doesn’t know the right answer yet may lead to this block.

So as you can add only one customer engagement platform, when you add the Transfer to agent block, the Operator API channel will be automatically added to this block. You will only need to specify some block options.