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.
Nota:
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>
}

 

Nota:
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”: [

]
}

 

Nota:
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

}


Nota: No hace falta introducir todo el texto en un solo mensaje, se podrá añadir tantos mensajes como sea necesario.
 
  • 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:
Este botón al ser pulsado, enviará al AC el mensaje que aparece en el texto del mismo.

{

"required": parámetro por defecto,

"parametro": parámetro por defecto,

"buttons": [

{

"type":"text",

"text": texto del botón;

},

...

]

}


  • Mensaje de tipo botón evento:
A diferencia del botón de texto, este al ser pulsado, envía un mensaje con un evento. En este caso, el texto del botón es solo descriptivo, el evento accionado es el parámetro

{

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

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.