Bot API

Ya incluido en los planes

VIP

Nuestra API para bot le permite conectar cualquier plataforma bot a cualquier conversación en JivoChat: 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

JivoChat 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 JivoChat se envian desde el endpoint del proveedor y en respuesta el proveedor envia los eventos al endpoint de JivoChat.

Todos los eventos de JivoChat 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 JivoChat 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 JivoChat 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 JivoChat. Todas las solicitudes de JivoChat 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 JivoChat y que tiene un periodo de vida limitado. Para hacer esto, JivoChat 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	JivoChat API → Bot	Evento de un nuevo mensaje del cliente al cual el bot necesita dar opciones de respuesta
BOT_MESSAGE	Bot → JivoChat API	Respuesta del bot al mensaje del cliente
INVITE_AGENT	Bot→ JivoChat API	Chat transferido al agente, si el bot no tiene opciones de respuestas
AGENT_JOINED	JivoChat API → Bot	El agente se ha conectado a la conversación junto al bot o al client
AGENT_UNAVAILABLE	JivoChat 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 -> JivoChat 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 JivoChat. 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 -> JivoChat 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 JivoChat. ú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 -> JivoChat 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 JivoChat. ú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 JivoChat. único en la cuenta del cliente
client_id	String	El identificador del usurio que escribe en uno de los canales de JivoChat. ú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	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
}

JivoChat Pro

4 veces mas chats
Desde COP 34,200 mensual