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 codesDescripción
200 OKSuccessful, respuesta regular
400 Bad RequestFormato de solicitud inválido. Debe verificar los campos solicitados para que estén en concordancia con el formato de la API
401 UnauthorizedError de autorización
403 ForbiddenAcceso denegado
404 Not FoundEl endpoint está mal formado
405 Method Not AllowedEste método o evento no es compatible
429 Too Many RequestLímite de solicitudes excedido
500 Internal Server ErrorError al procesar la solicitud
502 Bad GatewayEl servidor está sobrecargado
503 Service UnavailableEl servidor no está disponible
504 Gateway TimeoutFalló 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ódigoDescripción
invalid_clientError de autenticación del Token del cliente. Regresó con el código HTTP sin autorización
unauthorized_clientLa autorización falló por el header Autorización
invalid_requestLa 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 mensajeDirecciónDescripción
CLIENT_MESSAGEJivoChat API → BotEvento de un nuevo mensaje del cliente al cual el bot necesita dar opciones de respuesta
BOT_MESSAGEBot → JivoChat APIRespuesta del bot al mensaje del cliente
INVITE_AGENTBot→ JivoChat APIChat transferido al agente, si el bot no tiene opciones de respuestas
AGENT_JOINEDJivoChat API → BotEl agente se ha conectado a la conversación junto al bot o al client
AGENT_UNAVAILABLEJivoChat API → BotEvento 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

NombreTipoDescripción
idStringEvento identificador único, usado para iniciar sesión y debugging
client_idStringEl identificador del usuario que escribe a uno de los canales de JivoChat. Unico en la cuenta de los clientes
chat_idStringidentificador de chat, en el cual se da la conversación entre el usuario-agente. único en le cuenta del cliente
messageMessageMensaje 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

NombreTipoDescripción
idStringevento unico identificador, usado para inicio de sesión y debugging
chat_idStringidentificador de caso, en el cual sucede la conversación agente-cliente. único en la cuenta del cliente
messageMessageMessages 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

NombreTipoDescripción
idStringidentificador único del evento, usado para iniciar sesión y debugging
client_idStringel identificador del usuario que escribe a uno de los canales de JivoChat. único en la cuenta del cliente
chat_idStringidentificador 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

NombreTipoDescripción
idStringidentificador único del evento, usado para iniciar sesión y debugging
client_idStringel identificador del usuario que escribe a uno de los canales de JivoChat. único en la cuenta del cliente
chat_idStringidentificador 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

NombreTipoDescripción
idStringidentificador único del evento, usado para iniciar sesión y debugging
chat_idStringel identificador del usuario que escribe a uno de los canales de JivoChat. único en la cuenta del cliente
client_idStringEl 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 mensajeDescripción
TEXTmensaje solo
MARKDOWNmensaje en formato Markdown
BUTTONSbotones de respuesta

TEXT

Parámetros de mensajes

NombreTipoDescripción
textStringmensaje
button_idString (optional)ID del botón que el usuario hizo click
timestampStringcreació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

NombreTipoDescripción
contentStringeste mensaje está en formato Markdown. En la primera versión: link, bold, italic
textStringTexto de evaluación no es compatible con este tipo de mensajes, es por ello que el mensaje no será enviado al cliente
button_idString optionalID del botón que el usuario hizo click
timestampStringCreació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

NombreTipoDescripción
buttonsArraybotones con respuestas listas. Máximo 3 botones
titleStringTítulos para los botones
textStringTexto de evaluación no es compatible con este tipo de mensajes, es por ello que el mensaje no será enviado al cliente
button.textStringTexto de la respuesta preparada
button.idStringID de la respuesta preparada
timestampStringCreació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
}
Artículos relacionados
¿Tiene preguntas?
Envíenos un mensaje en el chat en vivo, estamos listos para ayudarle las 24 horas