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:

POST {apiUrl}/setWebhook
POST {apiUrl}/sendText
POST {apiUrl}/sendFile
POST {apiUrl}/closeChat
POST {apiUrl}/selectDestination
GET {apiUrl}/getDestinations

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

Parameter	Type	Description
`apiUrl`	`string`	API URL where Operator API requests will be routed to.
`url`	`string`	The webhook set by the `setWebhook` method. It will later be used to accept events routed to Tovie DialogStudio.
`ApiKey`	`string`	Channel 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

Parameter	Type	Mandatory	Description
`userId`	`string`	Yes	Client ID.
`text`	`string`	Yes	Text 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

Parameter	Type	Mandatory	Description
`userId`	`string`	Yes	Client ID.
`url`	`string`	Yes	File download link.
`fileName`	`string`	No	Name of the file to be downloaded.
`size`	`integer`	No	File 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

Parameter	Type	Mandatory	Description
`userId`	`string`	Yes	Client ID.
`text`	`string`	Yes	Text 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

Parameter	Type	Mandatory	Description
`userId`	`string`	Yes	Client ID assigned on the Tovie DialogStudio platform.
`destinationId`	`string`	Yes	Agent ID assigned by the agent application.
`userName`	`string`	No	The client’s first name. If no value is passed, the agent will see `{channel} {userId}` as the name.
`attributes`	`string`	No	Pre-chat field. Accepts JSON in the `{"key":"value"}` form. Parameters will be passed to the agent as additional client information.
`hiddenAttributes`	`string`	No	Pre-chat field that will not be sent to the agent. The format is similar to `attributes`.
`customData`	`string`	No	Additional 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

Parameter	Type	Description
`destinationId`	`string`	Agent group ID.
`name`	`string`	Agent group name.
`hasOnline`	`boolean`	Agent 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

Event	Description
`TextMessage`	Text message from the agent.
`FileMessage`	Attached file from the agent.
`Closed`	Message closed by the agent.
`SelectDestination`	Selected routing destination.

Request parameters

Parameter	Type	Mandatory	Description
`id`	`string`	Yes	Message identifier.
`userId`	`string`	Yes	Client ID.
`type`	`string`	Yes	Event type.
Employee
`employeeId`	`string`	Yes	Agent ID.
`firstName`	`string`	Yes	Agent first name.
`lastName`	`string`	Yes	Agent last name.
`avatarUrl`	`string`	Yes	Link to the avatar of the agent.
TextMessage
`text`	`string`	Yes	Text message sent by the agent.
FileMessage
`url`	`string`	Yes	File download link.
`name`	`string`	Yes	Name of the file to be downloaded.
`size`	`integer`	Yes	File size in bytes.
`comment`	`string`	Yes	Comment to the file being sent.
SelectDestination
`destinationId`	`string`	Yes	Agent group ID.
`name`	`string`	Yes	Agent group name.
`hasOnline`	`boolean`	Yes	Agent 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.

API methods​

POST /setWebhook​

POST /sendText​

POST /sendFile​

POST /closeChat​

POST /selectDestination​

GET /getDestinations​

Passing events to Tovie DialogStudio​

Event types​

Request parameters​

Connect the channel​

Transfer to agent​

API methods

POST /setWebhook

POST /sendText

POST /sendFile

POST /closeChat

POST /selectDestination

GET /getDestinations

Passing events to Tovie DialogStudio

Event types

Request parameters

Connect the channel

Transfer to agent