VERSIÓN API
Versión 2.0.0
GUÍA API
En esta sección se documenta la API de 1MillionBot, destinada a aquellas empresas desarrolladoras que deseen interactuar y probar nuestros servicios.
La API de 1MillionBot ofrece a las empresas el servicio de conexión entre sus clientes con un Agente Conversacional (AC) previamente creado y entrenado. Utilizando esta API, los desarrolladores podrán hacer:
- Crear usuarios.
- Activar una conversación.
- Enviar mensajes al AC.
La funcionalidad más importante de esta API es la del envío de mensajes al AC, la cual abstrae el proceso de conexión con Dialogflow. Dialogflow tiene su API, para más información entre aquí.
PETICIONES API
Para hacer llamadas a la API de 1MillionBot, crea una petición de tipo POST y añade la cabecera Content-Type: application/json. Los parámetros que se enviarán a la llamada vendrán en formato JSON. A continuación se detallará cada tipo de llamada con los datos necesarios.
GENERAR USUARIO
https://api.1millionbot.com/api/v2/update-user
Esta petición crea un usuario a partir de unos datos previamente recogidos o generados.
Formato del body:
{
"timezone": string_timezone,
"platform": plataforma,
"token": token_usuario,
"language": lang
}
Los anteriores campos son de tipo String. El token es generado anteriormente y el resto de datos se obtienen desde el navegador y/o dispositivo móvil. Para realizar pruebas, se pueden rellenar manualmente.
ACTIVAR CONVERSACIÓN
https://api.1millionbot.com/api/v2/send-welcome
Para iniciar la conversación entre un usuario y el Agente Conversacional,(AC) es necesario lanzar esta petición al principio del diálogo para establecer la conexión entre ambos.
Formato del body:
Dentro del campo response, podrán aparecer diferentes tipos de mensajes, como aparece en el apartado Formato de mensajes.
{
"token_bot":token del bot,
"token_user":token del usuario
}
token_user se corresponde con el token del usuario previamente almacenado en nuestra base de datos, y token_bot con el identificador proporcionado del AC. Ambos campos son String.
Esta petición, al igual que la de enviar mensaje, tiene diversos tipos de salidas dependiendo del tipo de mensaje que se envíe al usuario.
Formato de la respuesta:
{
"response": [
...
]
}
ENVIAR MENSAJE
https://api.1millionbot.com/api/v2/send-message
Es la llamada más importante de la API, es la base del servicio de chat y se realizará cada vez que el usuario interactúe con el AC.
Formato del body:
«bot»: <token del AC porporcionado por 1MillionBot>,
«message»: <mensaje del usuario>,
«user»: <token del usuario>,
«event»: <parámetro por defecto: 0>,
«source»: <web/mobile>,
«logged»: <true/false>
}
event es 1 cuando el mensaje tiene un evento asociado. Un evento fuerza al AC a responder sobre una intención de conversación concreta. Para especificar el evento, cuando event=1, el parámetro message será el nombre del evento a ejecutar
Formato de la respuesta:
«response»: [
…
]
}
La cantidad de mensajes de respuesta es variable. Además, en el Array response pueden aparecer tantos tipos de respuesta como se desee (ver tipos de mensaje). Es decir, el Agente Conversacional podrá responder más de un mensaje por respuesta, y de diferente tipo (por ejemplo: dos mensajes de texto, una imagen y dos links).
FORMATO DE MENSAJES DEL AC
La API de 1MillionBot soporta diferentes tipos de mensajes, cada uno tiene un formato diferente para ser identificable por los desarrolladores y lo puedan maquetar de distintas maneras.
- Mensaje de tipo texto:
{
"text": mensaje respuesta del AC
}
- Mensaje de tipo imagen:
{
"image": {
"alt": parámetro por defecto;
"redirection": url de la redirección,
"src": enlace fuente de la imagen
}
}
- Mensaje de tipo video:
{
"video": {
"src": enlace del video
}
}
- Mensaje de tipo link:
{
"link": {
"text": texto del nombre del link,
"url": enlace deseado
}
}
- Mensaje de tipo botó texto:
{
"required": parámetro por defecto,
"parametro": parámetro por defecto,
"buttons": [
{
"type":"text",
"text": texto del botón;
},
...
]
}
- Mensaje de tipo botón evento:
{
"required": parámetro por defecto,
"parametro": parámetro por defecto,
"buttons": [
{
"type": "event",
"text": descripción del botón,
"event": nombre del evento
},
...
]
}
ENTORNO DE PRUEBAS
Para poder tener un primer contacto con la API de 1MillionBot, se han creado enlaces destinados a realizar pruebas iniciales con nuestros servicios. Estas son las llamadas:
- https://api.1millionbot.com/api/v2/demo/update-user
- https://api.1millionbot.com/api/v2/demo/send-welcome
- https://api.1millionbot.com/api/v2/demo/send-message
El body de cada llamada tiene la misma forma que el mostrado anteriormente. Para el buen funcionamiento de estas llamadas, internamente se utilizará como token de usuario la constante demo_1, creada especificamente para estas pruebas. Desde 1MillionBot, aconsejamos utilizar la herramienta Postman para realizar las acciones necesarias.
En este link encontrarás los enlaces demo listos para ser probados desde la aplicación Postman.