Puede desarrollar módulos de bot para los chats (el nombre interno del servicio es MessageGateway). Los bots pueden escuchar lo que sucede en los chats y también realizar ciertas acciones mediante el Bot API: asignar diálogos a gestores o bots, escribir en los chats, reaccionar a comandos, etc.
Primero es necesario registrar el módulo en la cuenta de CRM mediante los métodos del API. Más detalles sobre esto se describen más abajo. Durante el registro se devuelve una URL y un token para trabajar con el Bot API del servicio MessageGateway. Todo el trabajo posterior se realiza a través del Bot API.
- Esquema general de interacción
- Registro y configuración del bot
- Obtención de información sobre el bot
- Trabajo con Bot API
Esquema general de interacción
Bot Usuario CRM MessageGateway
--------------------------------------------------------------------------------------------------
| | | |
1. | Creación -----------------> | |
| de la clave | |
| API | |
| | | |
| | | |
2. | Pulsa | |
| el botón «Conectar» --------------> | |
| en la ficha del Módulo | |
| en el Marketplace | |
| | Redirección |
3. | <------------------------------------------ del usuario |
| | al formulario de configuración |
| | y activación del Módulo |
4. | <------------------ Rellena el formulario | |
| | | |
5. Verificación de la clave API, | | |
de los permisos de la clave API -----------------------------------------------> |
y de la versión del API | | |
| | | |
6. Registro | Obtención |
del bot ----------------------------------------> del token ----------------> |
| | | |
| | Devolución del token |
7. | <--------------------------------------- y de la URL de acceso a |
| | MessageGateway |
| | | |
| | | |
8. | Rellena el formulario con las | |
| <--------------- configuraciones del bot | |
| | | |
9. Guardado | | |
de la configuración ---------------------------------------------------------------> |
| | | |
10. Redirección | | |
del usuario ---------------------------------------------------------------> |
a la cuenta | | |
de CRM | | |
| | | |
--------------------------------------------------------------------------------------------------Registro y configuración del bot
El registro de un nuevo bot, así como la modificación de la configuración de uno existente, se realiza mediante el método POST /api/v5/integration-modules/{code}/edit, al que es obligatorio pasar el parámetro vacío integrationModule[integrations][mgBot]={}. Si el módulo con el código code ya existe, el método modifica su configuración; en caso contrario, se crea un nuevo módulo.
Durante el registro es necesario indicar el nombre integrationModule[name] (no más de 32 caracteres), el código integrationModule[code], la URL base integrationModule[baseUrl] y el código único integrationModule[clientId], para poder identificar la cuenta del sistema. En caso de registro correcto, la respuesta contendrá la dirección del MessageGateway Bot API (info[mgBot][endpointUrl]) y la clave de acceso a este (info[mgBot][token]).
Toda la configuración posterior del bot debe realizarse en MessageGateway mediante el Bot API.
Para que el registro del bot sea exitoso, es necesario que la funcionalidad de chats esté activada en la cuenta del sistema. Al desactivar los chats, todos los módulos-bot se desactivarán automáticamente y, al volver a activar los chats, estos módulos no se activarán de forma automática.
Ejemplo de solicitud:
{
"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": {}
}
}Ejemplo de respuesta:
{
"success": true,
"info": {
"mgBot": {
"endpointUrl": "http://127.0.0.1:8080",
"token": "5bbdfd67ed17486e32363c95d462a39a138b215ccd9f87ef4c23e8f89f18e10a5"
}
}
}Obtención de información sobre el bot
La información sobre el bot se obtiene mediante el método GET /api/v5/integration-modules/{code}.
Ejemplo de respuesta:
{
"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
}
}
}
}Trabajo con Bot API
API Endpoint: https://mg-s1.retailcrm.pro/api/bot/v1/
La autorización se realiza mediante el token obtenido durante el registro del bot.
Para cada solicitud es necesario enviar este token en el encabezado
X-Bot-Token:X2EDxEta9U3lcsSV0dwdF38UvtSCxIuGh
Importante!
Se aplica un límite de 30 solicitudes por segundo con un mismo token. Si se superan estos límites de frecuencia, el API devuelve una respuesta con el estado HTTP
429 Too Many Requests.
Si no guardó el token durante el registro, puede obtenerlo de nuevo junto con la información del bot.
A continuación se indican enlaces a la documentación del Bot API, así como a clientes de API preparados para varios lenguajes.
- Documentación de Bot API
- Cliente de Bot API para Go
- Cliente de Bot API para Javascript
Si el bot va a reaccionar a comandos, estos deben registrarse mediante el método PUT /my/commands/{name} inmediatamente después del registro del módulo del bot.
El ciclo estándar posterior de trabajo con el Bot API se organiza de la siguiente manera:
- El bot se conecta al WebSocket y empieza a escuchar los eventos que le interesan
- Cuando llegan los eventos relevantes, el bot ejecuta acciones mediante llamadas a los métodos del Bot API
Importante!
Es necesario manejar la situación en la que el WebSocket se cierra, de forma normal o anómala, por parte de MessageGateway, y hacer que el bot intente reconectarse al WebSocket con cierto tiempo de espera.