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.