Bot API

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.

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

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

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

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

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

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

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

Ejemplo:

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

Message types

TEXT

Parámetros de mensajes

Ejemplo:

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

MARKDOWN

Parámetros de mensajes

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

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
}