General information
The naming, method types, and JSON response structure are developed in accordance with the accepted BRIX standards and cannot be altered by the client.
The base URLs and tokens for system interaction are specified in the messenger settings.
The logic of how an operator works with client sessions is implemented within the standard logic of live chats. It is the same for custom messengers as for other messengers, and using arbitrary messengers doesn’t provide additional functionality.
Messenger setup
Connecting an arbitrary messenger to a live chat is done similarly to other available messengers. For more details, refer to the section Connect messengers to a live chat.
Here is a list of settings that should be present in the arbitrary messenger for its connection to a live chat:
- Channel name for communication with the messenger of type
[string]. It doesn’t affect the interaction with the messenger. It serves as additional information and is displayed in the list of connected channels for the administrator and in the session for the operator. - Access token to the third-party messenger’s API (confirmation string) of type
[string]. It’s filled in when creating a channel for communication with the messenger. It will be sent with every message from the BRIX system to the messenger. It can be empty. - Messenger’s API URL of type
[string]is the URL (webhook) to which messages from the BRIX system will be sent.
API
Below are methods for the custom messenger’s interaction with BRIX.
All methods must return the following values:
200 OK.401 Unauthorized. This is returned if the token doesn’t match.404 Not Found. This is returned if the channel doesn’t exist.500 Internal Server Error. This is returned in case of an unexpected server error.
All methods have an unchangeable prefix. It is the base URL set by the installation settings of BRIX and the company.
BRIX methods for interaction with the messenger (BRIX —> Messenger)
Messenger connection request (POST Connect)
Request URL:
https://my-domain.com/api/messengers/external/test/webhook
Parameters for the request:
token. Token generated on the messenger’s side.channelId. ID of the channel in the BRIX system.data.webhook. Webhook for sending requests to the BRIX system.
Sample request body:
{
"type": "connect",
"token": "confirm",
"channelId": "ebf45efc-cc67-4b60-9e3f-121966ba9f30",
"data": {
"webhook": "https://my-domain.com/api/messengers/external/other/webhook/ebf45efc-cc67-4b60-9e3f-121966ba9f30"
}
}
Method to send a message to the messenger (POST Send Message)
Request URL:
https://my-domain.com/api/messengers/external/test/webhook
Parameters for the request:
token. Token generated on the messenger’s side.channelId. ID of the channel in the BRIX system.data.targetChatId. Chat ID in the messenger.data.text. Message text.data.files. Array of attachments.
Sample request body:
{
"type": "message",
"token": "confirm",
"channelId": "ebf45efc-cc67-4b60-9e3f-121966ba9f30",
"data": {
"targetChatId": "chat1",
"text": "text",
"files": [
{
"name": "file1.png",
"size": 12345,
"URL": "https://brix365.com/en/img/about/photo-staff.png"
}
]
}
}
Method to request a delivery notification (POST Send Message Outcome)
Request URL:
https://my-domain.com/api/messengers/external/test/webhook
If the message is successfully processed, then success will evaluate to true. If success = false or no response follows, retry sending the message with the specified messageId.
Sample request body:
{
"type": "messageOutcome",
"token": "confirm",
"data": {
"success": true,
"messageId": "message1"
}
}
Method to request user data (POST Get User Info)
Request URL:
https://my-domain.com/api/messengers/external/test/webhook
Parameters for the request:
token. Token generated on the messenger’s side.channelId. ID of the channel in the BRIX system.data.userId. User ID in the messenger.
Response:
Avatar. File in the base64 format.
Sample request body:
{
"type": "userInfo",
"token": "confirm",
"data": {
"userId": "user1"
}
}
Sample response:
{
"id": "extUser1"
"username": "JohnDoe"
"phoneNumber": "89990002266"
"avatar": "data:image/jpeg;base64,/9j/4AAQSkZJRg... "
}
Method to request a read receipt for a message (POST Mark Message As Read)
Request URL:
https://my-domain.com/api/messengers/external/test/webhook
Sample request body:
{
"type": "markAsRead",
"token": "confirm",
"data": {
"messageId": "message1"
}
}
Method to send a messenger disconnect notification (POST Disconnect)
Request URL:
https://my-domain.com/api/messengers/external/test/webhook
Sample request body:
{
"type": "disconnect",
"token": "confirm",
"channelId": "ebf45efc-cc67-4b60-9e3f-121966ba9f30"
}
Methods for Messenger Interaction with BRIX (Messenger —> BRIX)
Method for sending a message to BRIX (POST Send Message)
Request URL:
https://my-domain.com/api/messengers/external/other/webhook/8ec8228f-7ff2-462b-a8d7-4f9b3f62c253
Parameters for the request:
token. Token formed on the messenger side.data.externalMessageId. Message ID in the messenger.data.externalChatId. Chat ID in the messenger.data.externalUserId. User ID in the messenger.data.text. Message text.data.files. Array of attachments.
Sample request body:
{
"type": "message",
"token": "confirm2",
"data": {
"externalMessageId": "message63",
"externalChatId": "chat12",
"externalChatName": "Chat name: chat 12",
"externalUserId": "user12",
"text": "text test",
"files": [
{
"name": "file1.png",
"URL": "https://brix365.com/en/img/about/photo-staff.png"
}
]
}
}
Method to send a notification about a disconnect initiated by the messenger (POST Disconnect)
Request string:
https://my-domain.com/api/messengers/external/other/webhook/ebf45efc-cc67-4b60-9e3f-121966ba9f30
Sample request body:
{
"type": "disconnect",
"token": "confirm"
}
Method to request user data (POST Get User Info)
Request string:
https://my-domain.com/api/messengers/external/other/webhook/c5f9889f-0fcc-4112-a8bd-d1a93cd5ab53
Sample request body:
{
"type": "userInfo",
"token": "confirm",
"data": {
"userId": "95806fe5-f8e8-460c-b2be-ce607068726c"
}
}
Interaction requests
All requests are sent to the messenger’s webhook (API URL of the messenger) and contain the following information:
- Messenger token.
- Request type.
- Request data.
All requests should receive the 200 response, indicating successful execution.
Request types for BRIX interaction with a messenger (BRIX → Messenger):
Connect. Request to create a connection. Always used when creating a new channel in the BRIX system. It serves to meet the external messenger’s data preparation needs. If you do not require data preparation, return code 200.Message. Request to send a message to the client from the operator.UserInfo. Request to get user data: full name, login (unique identifier), phone number, avatar, etc.MarkMessageAsRead. Request to mark a message as read in an external messenger.Disconnect. Notification request about terminating interaction with the messenger.
Request types for messenger Interaction with BRIX (Messenger → BRIX):
Message. Request to send a message to the operator from the client.Disconnect. Notification request about terminating interaction initiated by the messenger.
Examples of requests and responses for interaction of BRIX with an arbitrary messenger
Let's look at examples of the following types of interaction between BRIX and an arbitrary messenger: connect, message, and userInfo.
- Configuring the connection between BRIX and a messenger to receive messages.
In the messenger connection settings in BRIX, specify the webhook and confirmation string. After connecting, a channel with a unique ID is created in the system. The messenger webhook will receive an event of type connect, containing the BRIX webhook:
{
"type": "connect",
"token": "123",
"channelId": "ebf45efc-cc67-4b60-9e3f-121966ba9f30",
"data": {
"webhook": "https://my-domen.com/api/messengers/external/other/webhook/ebf45efc-cc67-4b60-9e3f-121966ba9f30"
}
}
Response: 200 — ОК.
- Sending a message from a messenger to BRIX.
It is configured in several steps:
1. Request string:
https://my-domen.com/api/messengers/external/other/webhook/ebf45efc-cc67-4b60-9e3f-121966ba9f30
Request body:
{
"type": "message",
"token": "123",
"data": {
"externalMessageId": "extMsgId",
"externalChatId": "extChat1",
"externalChatName": "Chat name: chat 12",
"externalUserId": "extUser1",
"text": "sample",
"files": [
{
"name": "file1.png",
"URL": "https://elma365.com/ru/img/partners/partners-hero.png"
}
]
}
}
Response: 200 — ОК.
2. After a message is received in BRIX, the system will send a request to retrieve user information. An event of type userInfo will be sent to the messenger webhook:
{
"type": "userInfo",
"token": "123",
"data": {
"userId": "extUser1"
}
}
Example of a user information response from the messenger:
{
"id": "extUser1"
"username": "JohnDoe"
"phoneNumber": "89990002266"
"avatar": "data:image/jpeg;base64,/9j/4AAQSkZJRg... "
}
3. When the user information is received by BRIX, an event of type messageOutcome will be sent to the messenger's webhook, notifying that the message has been successfully received by the system:
{
"type": "messageOutcome",
"token": "123",
"data": {
"success": true,
"messageId": "message1"
}
}
Response: 200 — ОК.
- Receiving a message from BRIX.
The messenger's webhook receives an event of type message:
{
"type": "message",
"token": "123",
"channelId": "ebf45efc-cc67-4b60-9e3f-121966ba9f30",
"data": {
"targetChatId": "extChat1",
"text": "message from BRIX",
"files": [
{
"name": "file1.png",
"size": 12345,
"URL": "https://elma365.com/ru/img/partners/partners-hero.png"
}
]
}
}
Response: 200 — ОК.