You can develop bot modules for chats (the internal name of the service is MessageGateway). Bots can listen to what is happening in chats and also perform actions using the Bot API: assign dialogs to managers or bots, post messages to chats, respond to commands, etc.
First, you need to register the module in the CRM account using API methods. More details are provided below. When registering, you receive a URL and a token for working with the Bot API of the MessageGateway service. All further work is done via the Bot API.
- General interaction flow
- Registering and configuring the bot
- Retrieving information about the bot
- Working with Bot API
General interaction flow
Bot User CRM MessageGateway
--------------------------------------------------------------------------------------------------
| | | |
1. | Creating ------------------> | |
| an API | |
| key | |
| | | |
| | | |
2. | Clicks | |
| the “Connect” button -------------> | |
| in the Module card | |
| in the Marketplace | |
| | Redirect |
3. | <------------------------------------------ User |
| | to the configuration form |
| | and module activation form |
4. | <------------------ Fills out the form | |
| | | |
5. Verification of the API key, | | |
API key permissions ---------------------------------------------------------------> |
and API version | | |
| | | |
6. Bot registration | Token retrieval |
of the bot ---------------------------------------> (token) ---------------> |
| | | |
| | Token returned |
7. | <--------------------------------------- together with the URL |
| | for access to MessageGateway |
| | | |
| | | |
8. | Fills out the form with the | |
| <--------------- bot settings | |
| | | |
9. Saving | | |
bot settings -----------------------------------------------------------------------> |
| | | |
10. Redirecting | | |
the user ---------------------------------------------------------------> |
back to the | | |
CRM account | | |
| | | |
--------------------------------------------------------------------------------------------------Registering and configuring the bot
Registration of a new bot, as well as modification of an existing bot’s settings, is performed using the method POST /api/v5/integration-modules/{code}/edit, where you must pass the empty parameter integrationModule[integrations][mgBot]={}. If a module with the code code already exists, the method updates its settings; otherwise, a new module is created.
During registration, you must specify the name integrationModule[name] (no more than 32 characters), the code integrationModule[code], the base URL integrationModule[baseUrl], and the unique code integrationModule[clientId], which allows the system account to be identified. If the registration is successful, the response will contain the MessageGateway Bot API address (info[mgBot][endpointUrl]) and the access key for it (info[mgBot][token]).
All further configuration of the bot must be performed in MessageGateway via the Bot API.
For the bot to be successfully registered, the chats functionality must be enabled in the system account. If chats are disabled, all bot modules will be automatically disabled, and when chats are enabled again, those modules will not be re-enabled automatically.
Example request:
{
"code": "awesomebot-101",
"integrationCode": "awesomebot",
"active": true,
"name": "Awesome Bot",
"logo": "http://download.awesomebot.server.net/logos/robot.svg",
"clientId": "client-101",
"baseUrl": "https://awesomebot.server.net",
"accountUrl": "https://awesomebot.server.net/profile/client-101",
"actions": {
"activity": "/activity"
},
"integrations": {
"mgBot": {}
}
}Example response:
{
"success": true,
"info": {
"mgBot": {
"endpointUrl": "http://127.0.0.1:8080",
"token": "5bbdfd67ed17486e32363c95d462a39a138b215ccd9f87ef4c23e8f89f18e10a5"
}
}
}Retrieving information about the bot
Information about the bot is retrieved using the method GET /api/v5/integration-modules/{code}.
Example response:
{
"success": true,
"integrationModule": {
"code": "awesomebot-101",
"integrationCode": "awesomebot",
"active": true,
"freeze": false,
"name": "Awesome Bot",
"logo": "http://download.awesomebot.server.net/logos/robot.svg",
"native": false,
"clientId": "client-101",
"baseUrl": "https://awesomebot.server.net/",
"actions": {
"activity": "/activity"
},
"availableCountries": [],
"accountUrl": "https://awesomebot.server.net/profile/client101",
"integrations": {
"mgBot": {
"token": "5bbdfd67ed17486e32363c95d462a39a138b215ccd9f87ef4c23e8f89f18e10a5",
"isActive": true
}
}
}
}Working with Bot API
API Endpoint: https://mg-s1.retailcrm.pro/api/bot/v1/
Authorization is performed using the token obtained during bot registration.
For each request, you must send this token in the header
X-Bot-Token:X2EDxEta9U3lcsSV0dwdF38UvtSCxIuGh
Important!
A limit of 30 requests per second per token applies. If you exceed this rate limit, the API returns a response with HTTP status
429 Too Many Requests.
If you did not save the token during registration, you can retrieve it again along with the bot information.
Below are links to the Bot API documentation, as well as ready-made API clients for several languages.
- Bot API documentation
- Bot API client for Go
- Bot API client for Javascript
If the bot is going to react to commands, those commands must be registered using the method PUT /my/commands/{name} immediately after the bot module is registered.
The typical subsequent Bot API workflow is organized as follows:
- The bot connects to the WebSocket and starts listening for events it is interested in
- When relevant events are received, the bot performs actions via Bot API method calls
Important!
Make sure to handle the situation when the WebSocket is closed, either normally or abnormally, by MessageGateway, and ensure that the bot attempts to reconnect to the WebSocket after some timeout.