Public asynchronous API "Omnichannel" connectivity

Omnichannel is a universal channel with a public API designed to connect the Agent to the End Channels for which there is no brand connector built into the Platform. The user can organize such a universal channel using the Omnichannel Universal Connector.

Agent connection
Agent channel configuration in the Platform

The Agent needs to create and configure an Agent Channel with a Omnichannel connector.

Enter the Edit menu for your Agent settings.

In the window that appears, go to the Channels tab to configure channels, then:
1. Select Omnichannel channel type
2. Click the Add another channel button.

Integration with Omnichannel occurs through a Connector called “Omnichannel”, set it in the Channel field.
- If necessary, enter a title for this channel in the Title field.
- The headers of different agent channels may be the same.

After selecting Omnichannel, a link to the agent’s channel webhook will become available to you (app.chatbots webhook: URL field).

Enter the address of your server in the Channel webhook field: URL in the form https://{server_adress}, where {server_adress} is the Platform address. Important: A method will be substituted for the specified address when the Agent sends a response to a request from the client channel/server: https://your_company.com/send_message.
Set your token in the Channel webhook: Token field in the Agent Channel settings window. Important: the token must be specified if authorization on the client side is carried out via header. More details are described in the Client-side authorization section.

Activate the channel by switching the toggle switch so that the Agent starts responding to it after saving.

If the Agent has not been trained, a warning will appear. In this case, it is necessary to train the Agent and then try again to activate the Agent Channel.

After activation, if there are problems with its availability, a warning will be displayed (The channel will be activated despite the problems):
1. Can’t reach channel – displayed if the server does not respond to the specified URL;
2. Couldn’t register agent webhook – displayed if it was not possible to register a webhook in the removed channel.
Save Agent’s Channel – click on the Save button.
All settings will be applied only after saving.

Communication
Requests from the client channel/server to the Agent on the Platform.

Supported protocol and method:

HTTPS, POST with content-type JSON

Endpoint for receiving requests by the agent channel:

Requests are sent to the App.Chatbots Webhook URL specified when connecting the Agent Channel.

Endpoint format (App.Chatbots Webhook URL):

The platform deployed in the cloud

https://app.chatbots.gms-worldwide.ch/connector/omnichannel/omnichannel_message/{token}/bot_api_webhook

The platform is deployed in the client circuit

https://{server_adress}/connector/omnichannel/omnichannel_message/{token}/bot_api_webhook

Where:

{server_adress} — Platform address,

{token} — authorization token.

General request structure
Request body type:

{
  "event": (string),
  "chat_id": (integer),
  "visitor": {
    "id": (string),
    "fields": {
      Fields (object)
    }
  },
  "message": { 
    Message (object)
  }
 }

Important: the structure of the Message object depends on the type of message being transmitted (text, file, button click) and can consist of different types of data and fields.

Event type event

event – the type of event that the Agent processes according to a certain logic.

Supported event types:

new_message is an event that is transmitted to the Agent by the client channel/server and contains a message from the Interlocutor.
chat_id — identifier of the chat/dialogue/interlocutor on the client server (in the communication application – the final channel), on the basis of which a Chat is created with this Interlocutor in the Platform.

Visitor object

A visitor is an object containing information about the Interlocutor.

Visitor view:

{
  "id": (string — pseudo unique identifier of the Interlocutor assigned by the client-server),
  "fields": {
   "name": (string),
   "login": (string),
   "phone": (string),
   "email": (string),
   "site": (string)
   }
  }

Message object

Message is an object containing information passed to the Agent for processing.

{
"id": (string — client server side message identifier),
"kind": (string — message type),
"text": (string — interlocutor's message text),
"data": (JSON — data about the file or button pressed)
}

Supported message content

Below are examples of the contents of the Message object for various message types.

Text

Message view:

{
"id": (string),
"kind": "visitor",
"text": (string — interlocutor's message text)
}

File

Message view:

{
 "id": (string),
 "kind": "file_visitor",
 "data": {
  "id": (string — client server side message identifier),
  "state": (string — sending status of file),
  "name": (string — file name with extension ),
  "content_type": (string — Internet Media Type),
  "size": (integer — file size in bytes),
  "url": (string — URL file)
  }
 }

Important: the event will only be processed when state == ready is received.
When kind == file_visitor, the Public API “Omnichannel” receives data about the file and converts it into a text message for the Agent in the format: file:{file_type}|{file_id}|{file_url} . The Agent itself does not download the file.

Pressing a button

Message view:

{
  "id": (string),
  "kind": "keyboard_response",
   "data": {
     "button": {
      "id": (string — button id),
      "text": (string — button text)
     }
   }
 }

Platform response when a request is unsuccessful

The Agent channel is inactive or there is an error in the App.Chatbots Webhook token in the URL

HTTP status: 400 Bad Request
- BODY:

{

“error”: “There is no active channel for received event.”

}

A required parameter is missing in the request body
- HTTP status: 400 Bad Request
Incorrect URL specified
- HTTP status: 404: Not Found
Incorrect JSON of the request body: invalid event or kind parameter
- HTTP status: 200 OK
Incorrect JSON of the request body: other errors besides specifying invalid event or kind parameters
- HTTP status: 500 Internal Server Error
Internal server errors
- HTTP status: 500 Internal Server Error

Requests from the Platform to the client channel/server

Below are the formats, examples, and descriptions of requests from the “Omnichannel” Public API to the client’s server.

Base URL

Requests are sent to the URL of the client server specified in the Channel Webhook: URL field when the Agent Channel is connected.

URL format: https://{server_address}/{method}, where:

{server_adress} — Platform address,

{method} is one of the methods of the Public API “Omnichannel”.

Methods of the Public API “Omnichannel”:

/send_message — sending a message by the Agent to the Interlocutor.

Client-side authentication

Authorization can be done through:

Unique URL
- Must specify the URL containing the token in the Channel webhook: URL field when connecting the Agent Channel. In this case, the Channel webhook: Token field does not need to be filled in.
Header
- You need to specify the authorization token in the Channel webhook: Token field when connecting the Agent Channel. The token from the Channel webhook: Token field will be inserted into the header by default.
Authorization format using a token:
- Authorization: Token {token}
Authorization example:
- Authorization: Token ac650a3c369a4b9599ad52ab71943712

Transfer to operator

Transferring to an operator using the Change Chat Mode Slot is not supported in the current implementation of the Platform functionality.
It is proposed to transfer to the operator using External Request using the appropriate client method.

Important: The public API “Omnichannel” has a limited set of capabilities. If it is necessary for the Agent to use other methods from the client API, then work with these methods can be configured inside the Agent using the request constructor (External Request).

Channel service messages

Interaction with the client-server occurs through the Public API “Omnichannel” according to the account settings in the client service.

Mapping channel variables from a client-server channel

Channel Variables	Variable in the body of the incoming request
channel_visitor_id	visitor.id
channel_conversation_id	chat.id
channel_visitor_firstname	visitor.fields.name
channel_visitor_lastname	–
channel_visitor_account	visitor.fields.login
channel_visitor_phone	visitor.fields.phone
channel_visitor_email	visitor.fields.email
channel_visitor_source	visitor.fields.site

Opportunities to communicate via Omnichannel

Functional	Availability	Description
channel_chat_id	Yes	<client chat_id>\|omnichannel
Messages will reach the interlocutor if the agent writes first in an existing chat	At the discretion of the channel
Buttons	Yes	Clicking the button comes as button label text.
Transfer to the operator	No	Transfer to an operator via the Change Chat Mode slot is not supported in the current implementation of the Platform functionality. Transfer to the operator can be done “manually” via External Request.
Transferring files as files from the Agent (Attachment slot)	No
Transferring files as links from the Agent (Attachment slot)	Yes
Receiving a file from the Interlocutor into a script	Yes	Format: file:File type\|File ID\|File link
Delivery of messages over 1000 characters from Agent to Interlocutor	At the discretion of the channel
Using markdown	No