Bot API

Ver otro artículo

Nuestra API para bot le permite conectar cualquier plataforma bot a cualquier conversación en Jivo: chat de sitio web, mensajería instantánea, redes sociales, etc. Cuando añade un bot, todas las conversaciones se enviarán primero al proveedor de bot para que sean procesadas.

Si tiene su propio bot o cualquier plataforma que quisiera conectar a nuestra plataforma, por favor envíenos un correo para generar un ID para el proveedor.

Intercambio de datos

Jivo seria quién inicia el intercambio. esto sucede cuando hay un mensaje entrante del cliente. Los eventos se intercambian con el proveedor de bot a través de webhooks. Todos los eventos de Jivo se envian desde el endpoint del proveedor y en respuesta el proveedor envia los eventos al endpoint de Jivo.

Todos los eventos de Jivo y del proveedor de bot se envian en solicitudes HTTPS utilizando el método POST en el formato application/JSON. El timeout es de 3 segundos y el número de intentos es de 2 hasta que una respuesta regular sea recibida, de otro modo, el cliente será transferido al agente. Esto le da 3 segundos para actualizar el software en el servidor, lo cuál será suficiente en la mayoria de los casos.

La URL del endpoint del proveedor de bot puede crearla como guste. El endpoint de Jivo se configura de la siguiente forma: bot.jivosite.com/webhooks/{provider_id}, en dónde provider_id es el identificador único del proveedor, se genera para cada uno por separado.

Códigos de respuesta

La tabla a continuación le muestra los posibles códigos de respuesta de Jivo hacia el provedor bot.

Response codes Descripción
200 OK Successful, respuesta regular
400 Bad Request Formato de solicitud inválido. Debe verificar los campos solicitados para que estén en concordancia con el formato de la API
401 Unauthorized Error de autorización
403 Forbidden Acceso denegado
404 Not Found El endpoint está mal formado
405 Method Not Allowed Este método o evento no es compatible
429 Too Many Request Límite de solicitudes excedido
500 Internal Server Error Error al procesar la solicitud
502 Bad Gateway El servidor está sobrecargado
503 Service Unavailable El servidor no está disponible
504 Gateway Timeout Falló al ejecutar la solicitud

En caso de un evento de emergencia, se recomienda que la información del errorsea transmitida como respuesta en el Body con el siguiente formato:

{
  "error" :
    {
      "code": "<error code>",
      "message": "<human-readable error message>"
    }
}

Códigos de error

Código Descripción
invalid_client Error de autenticación del Token del cliente. Regresó con el código HTTP sin autorización
unauthorized_client La autorización falló por el header Autorización
invalid_request La solicitud no contiene un parámetro requerido, un parámetro no compatible está en uso, hay un parámetro doble, existen diferentes credenciales u otros errores de solicitud

Autenticación

La Autenticación del cliente del proveedor del bot desde la cual se accede al API se obtiene mediante un token, el cual es generado desde el proveedor. El cliente recibe el token desde el proveedor del bot y lo añade en las configuraciones del canal de bot conectado en Jivo. Todas las solicitudes de Jivo al bot y viceversa se hacen con este token, el cual se envia en formato de solicitud URL:

POST https://{bot_endpoint}/token
Content-Type: application/json

POST https://bot.jivosite.com/webhooks/{provider_id}/{token}
Content-Type: application/json

...

POST https://bot-provider-endpoint.com/zhFZipzT:8560a55a9af37d68782b3234a84f344c592ab766
Content-Type: application/json

POST https://bot.jivosite.com/webhooks/Ee0CRkyDAp/zhFZipzT:8560a55a9af37d68782b3234a84f344c592ab766
Content-Type: application/json

Autorización

Además de la autenticación, puede usar mecanismos de seguridad adicionales en la forma de un token de autorización. el cual es suministrado por el proveedor a Jivo y que tiene un periodo de vida limitado. Para hacer esto, Jivo primero recibe el acceso temporal del token a cambio de una llave secreta y el client_id, el cuál después se transmite cada vez que se acceda de nuevo al header en Autorización header. Ejemplo:

POST https://bot-provider-endpoint.com/zhFZipzT:8560a55a9af37d68782b3234a84f344c592ab766
Content-Type: application/json
Authorization: 92753d11-4aef-459a-8d45-1c1faabb6e36

...

POST https://bot.jivosite.com/providers/Ee0CRkyDAp/zhFZipzT:8560a55a9af37d68782b3234a84f344c592ab766
Content-Type: application/json
Authorization: 92753d11-4aef-459a-8d45-1c1faabb6e36

Tipos de eventos

Tipo de mensaje Dirección Descripción
CLIENT_MESSAGE Jivo API → Bot Evento de un nuevo mensaje del cliente al cual el bot necesita dar opciones de respuesta
BOT_MESSAGE Bot → Jivo API Respuesta del bot al mensaje del cliente
INVITE_AGENT Bot→ Jivo API Chat transferido al agente, si el bot no tiene opciones de respuestas
AGENT_JOINED Jivo API → Bot El agente se ha conectado a la conversación junto al bot o al client
AGENT_UNAVAILABLE Jivo API → Bot Evento que informa que al momento no hay agentes disponibles en la aplicación para recibir chats

CLIENT_MESSAGE

Caso: el operador de bot está conectado al canal -> el cliente escribe un mensaje -> Jivo envia el mensaje al proveedor de bot -> el mensaje es procesado y la respuesta se envia dependiendo del escenario.

Parámetros de eventos

Nombre Tipo Descripción
id String Evento identificador único, usado para iniciar sesión y debugging
client_id String El identificador del usuario que escribe a uno de los canales de Jivo. Unico en la cuenta de los clientes
chat_id String identificador de chat, en el cual se da la conversación entre el usuario-agente. único en le cuenta del cliente
message Message Mensaje del cliente

Ejemplo:

{
  event: "CLIENT_MESSAGE",
  id: "123e4567-e89b-12d3-a456-426655440000",
  client_id: "1234",
  chat_id: "213123",
  message: {
    type: "TEXT",
    text: "Hello! How much is the delivery?",
    timestamp: 1583910736
  }
}

BOT_MESSAGE

Caso: el cliente escribe un mensaje -> jivo envia el mensaje al proveedor del bot -> el mensaje es procesado -> el bot responde con un mensaje listo -> el mensaje es enviado al cliente.

Parámetros del evento

Nombre Tipo Descripción
id String evento unico identificador, usado para inicio de sesión y debugging
chat_id String identificador de caso, en el cual sucede la conversación agente-cliente. único en la cuenta del cliente
message Message Messages from the bot

Ejemplo

{
  event: "BOT_MESSAGE",
  id: "123e4567-e89b-12d3-a456-426655440000",
  message: {
    type: "BUTTONS",
      title: "Are you interested in delivery within the New York area?",
      text: "Are you interested in delivery within the New York area? Yes / No"
      timestamp: 1583910736,
      buttons: [
        {
          text: "Yes",
          id: 1,
        }, {
          text: "No",
          id: 2
        }
      ]
  }
}

INVITE_AGENT

Caso: el cliente escribe un mensaje -> Jivo envia el mensaje al proveedor del bot -> el mensaje es procesado -> el bot no tiene una respuesta -> el chat se transfiere a un agente.

Parámetros del evento

Nombre Tipo Descripción
id String identificador único del evento, usado para iniciar sesión y debugging
client_id String el identificador del usuario que escribe a uno de los canales de Jivo. único en la cuenta del cliente
chat_id String identificador del chat, en el cual sucede la comunicación entre agente-cliente. único en la cuenta del cliente

Ejemplo

{
  event: "INVITE_AGENT",
  id: "123e4567-e89b-12d3-a456-426655440000",
  client_id: "1234",
  chat_id: "213123"
}

AGENT_JOINED

Caso: el cliente escribe un mensaje -> Jivo envia el mensaje al proveedor del bot -> el mensaje es procesado -> el bot no tiene una respuesta -> el chat se transfiere a un agente -> el agente se une al chat.

Parámetros del evento

Nombre Tipo Descripción
id String identificador único del evento, usado para iniciar sesión y debugging
client_id String el identificador del usuario que escribe a uno de los canales de Jivo. único en la cuenta del cliente
chat_id String identificador del chat, en el cual sucede la comunicación entre agente-cliente. único en la cuenta del cliente

Ejemplo:

{
  event: "AGENT_JOINED",
  id: "123e4567-e89b-12d3-a456-426655440000",
  client_id: "1234",
  chat_id: "213123"
}

AGENT_UNAVAILABLE

Caso: El proveedor del bot transfiere el chat al agente, pero no hay agentes disponibles en la aplicación, entonces, de acuerdo con el script del bot, enviará un mensaje al cliente pidiendo datos de contacto.

Parámetros del evento

Nombre Tipo Descripción
id String identificador único del evento, usado para iniciar sesión y debugging
chat_id String el identificador del usuario que escribe a uno de los canales de Jivo. único en la cuenta del cliente
client_id String El identificador del usurio que escribe en uno de los canales de Jivo. único en la cuenta del cliente

Ejemplo:

{
  event: "AGENT_UNAVAILABLE",
  id: "123e4567-e89b-12d3-a456-426655440000",
  chat_id: "213123",
  client_id: "213123"
}

Message types

Tipo de mensaje Descripción
TEXT mensaje solo
MARKDOWN mensaje en formato Markdown
BUTTONS botones de respuesta

TEXT

Parámetros de mensajes

Nombre Tipo Descripción
text String mensaje
button_id String (optional) ID del botón que el usuario hizo click
timestamp String creación de etiqueta de tiempo, unix time

Ejemplo:

{
  type: "TEXT",
  text: "Hello! What is your weekend routine?",
  button_id: "123",
  timestamp: 1583910736
}

MARKDOWN

Parámetros de mensajes

Nombre Tipo Descripción
content String este mensaje está en formato Markdown. En la primera versión: link, bold, italic
text String Texto de evaluación no es compatible con este tipo de mensajes, es por ello que el mensaje no será enviado al cliente
button_id String optional ID del botón que el usuario hizo click
timestamp String Creación de la etiqueta de tiempo del mensaje, unix time

Example

{
  type: "MARKDOWN",
  content: "To disable **PUSH notifications**, please follow the steps described in our [instructions](https://site.com/page_url)",
  text: "To disable PUSH notifications, please follow the steps described in our instructions https://site.com/page_url",
  timestamp: 1583910736
}

BUTTONS

Parámetros de mensajes

Nombre Tipo Descripción
buttons Array<button> botones con respuestas listas. Máximo 3 botones
title String Títulos para los botones
text String Texto de evaluación no es compatible con este tipo de mensajes, es por ello que el mensaje no será enviado al cliente
button.text String Texto de la respuesta preparada
button.id String ID de la respuesta preparada
timestamp String Creación de la etiqueta de tiempo del mensaje, unix time

Ejemplo:

{
  type: "BUTTONS",
  title: "Could you please specify the desired delivery service?"
  text: "Could you please specify the desired delivery service? PEC and Boxberry are available",
  buttons: [
    {
      text: "PEC",
      id: "1"
    },
    {
      text: "Boxberry",
      id:"2"
    }
  ],
  timestamp: 1583910736
}

¿Aún tiene dudas? Nuestro equipo de soporte está disponible 24/7 en el chat de nuestra web y con gusto le atenderá