Integration mechanism between the bot and the system

It is possible to develop bot modules for chats (the name of the service is MessageGateway). Bots can listen to what is happening in chats and execute some sort of actions by means of Bot API: assign dialogs to managers or bots, write in chats, react to commands and etc.

First of all you should register the module in your retailCRM account using API methods. Find more details about this below. URL and token of the MessageGateway service for working with Bot API are returned to you during the registration process. All further work is based on Bot API.

General interaction scheme


           Bot                        User                     retailCRM                MessageGateway 
       --------------------------------------------------------------------------------------------------
            |                           |                          |                          |
1.          |                      Creation of  -----------------> |                          |
            |                        API-key                       |                          |
            |                           |                          |                          |
            |                           |                          |                          |
2.          |                         Clicks                       |                          |
            |                    “Connect” button  --------------> |                          |
            |                   on the module page                 |                          |
            |                     in Marketplace                   |                          |
            |                           |                     Redirection                     |
3.          | <-------------------------------------------    of the user                     |
            |                           |              to the configuration form              |
            |                           |                for module activation                |
4.          | <---------------- Fills in the form                  |                          |      
            |                           |                          |                          |
5.  Checking the API key,               |                          |                          |
   rights for the API key  --------------------------------------> |                          |
      and API version                   |                          |                          |
            |                           |                          |                          |
6.         Bot                          |                       Getting                       |
       registration  --------------------------------------->   a token    -----------------> |
            |                           |                          |                          |
            |                           |                  Returning the token                |
7.          | <---------------------------------------    and URL for access to               |
            |                           |                    MessageGateway                   |
            |                           |                          |                          |
            |                           |                          |                          |
8.          |                    Fills in the form                 |                          |
            | <------------    with the bot settings               |                          |
            |                           |                          |                          |
9.        Saving                        |                          |                          |
     the bot settings ----------------------------------------------------------------------> |
            |                           |                          |                          |
10.    Redirection                      |                          |                          |
       of the user    -------------------------------------------> |                          |
     to the retailCRM                   |                          |                          |
         account                        |                          |                          |
            |                           |                          |                          |
       --------------------------------------------------------------------------------------------------

Bot registration and configuration

The bot registration and changing the existing settings are made by means of the POST method /api/v5/integration-modules/{code}/edit, in which empty parameter integrationModule[integrations][mgBot]={} must be passed. If the module with code code already exists, the method changes its settings, otherwise, a new module is created.

During the registration you should specify the name integrationModule[name], the code integrationModule[code], the base URL integrationModule[baseUrl] and the unique code integrationModule[clientId] to identify the system account. If the registration is successful, the response will contain the address of MessageGateway Bot API (info[mgBot][endpointUrl]) and its access key (info[mgBot][token]). Further bot configuration should be made in MessageGateway by means of Bot API.

For successful registration of the bot it is necessary to have chat functionality enabled in the system. If chats are disabled, all bot modules will be disabled automatically and when enabling the chats, they will not be enabled.

Query example:

{
    "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": {}
    }
}

Response example:

{
  "success": true,
  "info": {
    "mgBot": {
      "endpointUrl": "http://127.0.0.1:8080",
      "token": "5bbdfd67ed17486e32363c95d462a39a138b215ccd9f87ef4c23e8f89f18e10a5"
    }
  }
}

Getting information about the bot

Getting information about the bot by means of the GET method /api/v5/integration-modules/{code}.

Response example:

{
  "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

Links to documentation on Bot API and to already generated API clients in context of some languages are below.

If the bot reacts to commands, they should be registered using the method PUT /my/commands/{name} immediately after the registration of the bot module.

Further cycle of work with Bot API is structured into the following way:

  1. The bot connects to WebSocket and starts listening to the events it is interested in
  2. When receiving those events, the bot executes actions via calling Bot API methods.

It is important to ensure that when websocket is closed normally or abnormally from the side of MesageGateway, the bot with some timeout attempts to reconnect to the websocket.


PrintEditHistory
Page last modified on November 12, 2020, at 02:03 PM