API del chat
El API del chat le permite organizar el proceso de solicitudes de clientes de cualquier fuente, tanto desde la aplicación móvil como la del computador, también le permite personalizar el widget de su sitio web. Los agentes recibirán las llamadas en la aplicación e JivoChat de igual forma que en los otros canales.
El mecanismo del Webhooks se utiliza para realizar integraciones. JivoChat provee un endpoint para recibir el estado de los canales y transmitir los mensajes de los clientes y en el lado de un sistema integrado debe existir un endpoint para transmitir la respuesta del agente al cliente.
El endpoint de JivoChat contiene strings aleatorios para protegerse de fuerza bruta así como para identificar el canal JIVO_PUBLIC_ID.
Para integrar desde JivoChat, inicia sesión desde la versión web de JivoChat o en la instalada. Vaya a los "Ajustes"-> "Añadir canales" -> "Chat API".
Haga clic en "conectar el Api del chat"
Ingrese el nombre del canal, la URL del servidor para su webhook, active o no la códificación fragmentada, selecciona cuáles agentes estarán asignados para recibir chats del nuevo canal que estás creando y haz clic en "añadir canal"
Ahora verá la URL de JivoChat que podrá usar.
¡Eso es todo! Ahora lo que debe hacer es continuar con el resto de las instrucciones para entener como trabajar con la URL generada.
Principio general de trabajo#
Flujo principal del trabajo en la integración#
title JivoSite-Webhooks Channel
Customer API->JivoSite: Channel Status HTTP GET
JivoSite->Customer API: Online (1)
Customer API->User: Show custom chat window
User->Customer API: Type User Message
Customer API->JivoSite: User Message HTTP POST
JivoSite->Agent: User Message
Agent->JivoSite: Agent Message
JivoSite->Customer API: Agent Message HTTP POST
Customer API->User: Draw Agent Message
Descripción del protocolo#
Customer API->JivoSite: Chat Status
GET https://wh.jivosite.com/<some random string>/JIVO_PUBLIC_ID/status
La respuesta estándar es 200 OK, con el cuerpo como integrado:
0 – el chat no está disponible. Los agentes están desconectados o el chat no está disponible en la web
1 – El chat está disponible, los agentes están en línea
Si no hay un canal en JivoChat con el id JIVO_PUBLIC_ID, el servidor responderá en HTTP con el estado 404.
Si la respuesta es irregular, le pedimos que nos contacte.
Customer API->JivoSite: User Message
POST https://wh.jivosite.com/<string aleatória >/JIVO_PUBLIC_ID
{
"sender" :
{
"id" : "12345",
"name" : "John Doe",
"photo" : "https://examplo.com.br/foto.jpg",
"url" : "https://site.com.br/exemplo/pagina.html",
"phone" : "12345678901",
"email" : "john@doe.сom",
"invite" : "Olá! Como posso ajudar?"
},
"message" :
{
"type" : "text",
"id" : "customer_message_id",
"text" : "Mensagem de texto do usuário"
}
}
sender.id - (string requerida o integrador) identificador del cliente en el Customer API. Si este campo está en blanco, el mensaje no se enviará.
sender.name, phone, email – campos opcionales (string). Si JivoChat los recibe, mostrará la información recibida por el agente. Si no, la información del cliente se mostrará como anónima. Estos valores se pueden alterar durante un chat.
sender.photo – link opcional a la imagen avatar del cliente. El link debe iniciar con: "http: //" o "https: //". El tamaño de imagen recomendada es de 128 * 128 px png | jpg | gif. La aplicación intentará mostrar esas imágenes pero no se garantiza su correcto funcionamiento.
sender.invite – textos de invitación opcional. Funciona de forma similar que la función "invitación en nombre del agente" (acción del trigger) en el widget. La lógica de mostrar la invitación es implementada en el chat en el lado del Customer API, mientras que el texto de invitación puede ser enviado al campo sender.invite y los agentes podrán verlo y entender el contexto en el cual el cliente lo ha realizado.
message.id – mensaje que identifica el Customer API. Solo será visible en los logs. Se utilizará en la próxima actualización para la notificación de enviado/leído.
message.type - (requerido) - "text" constante. Otro tipo de mensajes aún no son compatibles, pero lo serán en el futuro.
message.text - (requerido para el type == text) – el string del mensaje del cliente hasta de 1000 caracteres. Si hay más de 1000 caracteres, el mensaje se cortará.
La respuesta estándar es 200 OK. Si el código de respuesta es diferente de 200, puede contactarnos para verificar.
Si no hay un canal en JivoChat con JIVO_PUBLIC_ID, el servidor responderá en HTTP con el estado 404.
JivoSite->Customer API: Agent Message
POST <API do Cliente HTTPS-endpoint URL>/JIVO_PUBLIC_ID
{
"sender" : {
"name" : "Nome do Operador",
"photo" : "URL da Foto do Operador"
},
"recipient" : {
"id" : "12345"
},
"message" : {
"type" : "text",
"id" : "jivo_message_id",
"text" : "Texto da Mensagem do Operador"
}
}
sender.name – nombre del agente quien escribió el mensaje.
sender.photo – link de imagen – avatar del agente.
recipient.id – identificador del cliente en el Customer API. Lo recibimos en el mensaje entrante y respondemos sin cambios.
message.id – identificador del mensaje en JivoChat. Se usará en el futuro para notificaciones de enviado/leído.
La respuesta estándar es 200 OK.
La respuesta del BODY es en formato JSON:
{ "result" : "ok" }
o
{ "error" : { "code" : <error code>, "message" : "<human-readable error message>" } }
Un mensaje de error será mostrado al agente en la conversación en JivoChat. Tal vez no se muestre dependiendo del código de error.
Registro de notificación de mensajes
Para la notificación de un mensaje configurado, se utiliza un mensaje con la indicación type:
type: "typein" – el inicio de un mensaje configurado.
type: "typeout" – el final de un mensaje configurado.
Otros campos con type son ignorados.
Funciona de igual forma en ambas direcciones, desde JivoChat en el Customer API y desde el Customer API a JivoChat.
Mensajes multimedia
Los mensajes multimedia se transmiten del mismo modo que los mensajes de texto, pero tienen un Type especial y campos adicionales. La composición de los campos requeridos y el valor del campo Type para cada media type soportado están en la siguiente lista:
Type field value | Required additional fields | Type |
---|---|---|
video | file, file_name, file_size | video |
audio | file, file_name, file_size | audio |
voice | file, file_name, file_size | voice message |
photo | file, file_name, file_size | image |
sticker | file, file_name, file_size | sticker |
document | file, file_name, file_size | file (link to file) |
location | latitude, longitude | geo-location |
Los mensajes óptimos de campo multimedia están a continuación:
Multimedia message field | Description |
---|---|
string file | http(s) file url |
string thumb | http(s) url for thumb image(w320px) |
string emoji | possible replacement of media with a unicode character |
number file_size | file size in bytes, integer positive |
string file_name | user-defined file name |
number duration | flow duration in seconds, integer positive |
number width | width in pixels, integer positive |
number height | height in pixels, integer positive |
string text | text message or comment |
string performer | author (composer, performer, etc.) |
string title | title |
number latitude | real latitude |
number longitude | real longitude |
Reenviar mensajes
Eventos, en el formato de solicitud http (s), se envían al servidor Customer API 3 veces cada 3 segundos, hasta que se reciba una respuesta válida. Esto le da 6 segundos para actualizar el software en el servidor, lo cual es suficiente en la mayoría de los casos. Si el servidor no está disponible, responderá con un error en 9 segundos. Estas configuraciones por defecto le permitirán recibir una respuesta de quien envía rápidamente. En caso de timeout o error del Customer API, el agente verá un mensaje de error en el chat.
Solicitud Chunked
JivoChat puede enviar solicitudes al Customer API con ambos Content-Length field y en el Chunked encoding.