Operator API
You can use the Operator API to connect any customer engagement platform to the chatbot project created on Aimylogic. When the customer engagement platform is integrated with Aimylogic, 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
{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 Aimylogic. 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 Aimylogic. |
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 Aimylogic 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 Aimylogic
{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 Aimylogic 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.