Cómo configurar una conexión WebSocket en WhatChat: Guía paso a paso
Los WebSockets establecen una conexión continua entre el cliente y el servidor, lo que permite una comunicación bidireccional. WhatChat utiliza esta conexión para ofrecer actualizaciones en tiempo real sobre los eventos de la plataforma. Para conectarse al WebSocket de WhatChat, simplemente proporcione un token y siga las instrucciones de configuración que se detallan en esta guía.
Nota: Esta función es experimental y la documentación puede cambiar con cada lanzamiento. Además, no se garantiza la compatibilidad hacia atrás, por lo que es importante asegurarse de utilizar la última versión de la implementación.
¿Por qué debería utilizar una conexión WebSocket? #
Una conexión WebSocket permite actualizaciones de datos en tiempo real, lo que la hace ideal para clientes, como los SDK para Android o iOS de WhatChat. Esto ayuda a actualizar el tablero sin necesidad de recargar la página, mejorando así la experiencia del usuario y aumentando la productividad de los agentes.
¿Cómo configurar una conexión WebSocket con WhatChat? #
Para configurar una conexión WebSocket con WhatChat, necesitas iniciar la conexión con el token de autenticación PubSub proporcionado por WhatChat. La URL para la conexión es wss://<tu-url-de-instalación>/cable. Si estás utilizando WhatChat Cloud, puedes usar wss://app.whatchat.com/cable como URL.
Un token PubSub es un token que se utiliza para autenticar un cliente al conectarse a un servicio PubSub (publicar-suscribirse). El cliente debe presentar este token al servicio para establecer una conexión y comenzar a publicar o suscribirse a mensajes.
Hay dos tipos de tokens PubSub disponibles en WhatChat, que se enumeran a continuación.
-
Token PubSub de Usuario: Este token tiene los privilegios de un agente/admin y recibiría todos los eventos mencionados más adelante en la página. Puedes obtener el token PubSub llamando a la API de Perfil.
-
Token PubSub de Contacto: WhatChat genera un token PubSub único para cada sesión de un contacto. Este token se puede utilizar para conectarse al WebSocket y recibir actualizaciones en tiempo real para la misma sesión. Cuando se crea un contacto a través de las APIs públicas, el
pubsub_tokense incluye en el payload de respuesta. Este token solo otorga acceso a eventos relacionados con la sesión actual, comoconversation.created,conversation.status_changed,message.created,message.updated,conversation_typing_on,conversation_typing_offypresence.update.
Consulta las API de Cliente para construir integraciones orientadas al cliente utilizando WhatChat.
Nota: Este token puede rotarse regularmente según tu tipo de instalación. Asegúrate de estar utilizando el token más reciente.
¿Cómo conectarse al WebSocket de WhatChat? #
Para conectarse al WebSocket de WhatChat, utiliza el comando subscribe e incluye tu pubSubToken, accountId y userId (si usas un token de usuario) en la solicitud de conexión. Aquí hay un ejemplo de cómo puedes conectarte a WhatChat.
// Agrega un método auxiliar para convertir JSON a cadena
const stringify = (payload = {}) => JSON.stringify(payload);
const pubSubToken = "<contact/user-pub-sub-token>";
const accountId = "<tu-id-de-cuenta-en-entero>";
const userId = "<id-de-usuario-en-entero-si-usa-token-de-usuario>";
const connection = new WebSocket(
"wss://app.whatchat.com/cable"
);
connection.send(
stringify({
command: "subscribe",
identifier: stringify({
channel: "RoomChannel",
pubsub_token: pubSubToken,
account_id: accountId,
user_id: userId,
}),
})
);
// La cadena esperada en connection.send tiene el siguiente formato:
// {"command":"subscribe","identifier":"{\\"channel\\":\\"RoomChannel\\",\\"pubsub_token\\":\\"tu-token-pubsub\\",\\"account_id\\": id_cuenta_entero,\\"user_id\\":id_usuario_entero}"}
Publicando presencia en el servidor WebSocket #
Para mantener el estado en línea de tus usuarios en WhatChat, puedes enviar un evento de actualización de presencia a WhatChat cada 30 segundos. Esta acción mantendrá el estado del agente/contacto en línea.
¿Cómo actualizar la presencia de un agente/admin?
Para actualizar la presencia de un agente o administrador, envía el siguiente payload al servidor:
const userPayload = stringify({
command: "message",
identifier: stringify({
channel: "RoomChannel",
pubsub_token: "<token-pubsub-de-usuario>",
account_id: accountId,
user_id: userId,
}),
data: stringify({ action: "update_presence" }),
});
connection.send(userPayload);
// La cadena esperada en connection.send tiene el siguiente formato:
// {"command":"message","identifier":"{\\"channel\\":\\"RoomChannel\\",\\"pubsub_token\\":\\"tu-token-pubsub\\",\\"account_id\\": id_cuenta_entero,\\"user_id\\":id_usuario_entero,\"data\":\"{\\"action\\":\\"update_presence\\"}\"}"}
¿Cómo actualizar la presencia de un contacto?
Para actualizar la presencia de un contacto, envía el siguiente payload al servidor:
const agentPayload = stringify({
command: "message",
identifier: stringify({
channel: "RoomChannel",
pubsub_token: "<token-pubsub-de-usuario>",
}),
data: stringify({ action: "update_presence" }),
});
connection.send(agentPayload);
// La cadena esperada en connection.send tiene el siguiente formato:
// {"command":"message","identifier":"{\\"channel\\":\\"RoomChannel\\",\\"pubsub_token\\":\\"tu-token-pubsub\\","data":"{\\"action\\":\\"update_presence\\"}"}
Payload del WebSocket #
Objetos #
Un evento puede contener cualquiera de los siguientes objetos como payload. Los diferentes tipos de objetos soportados en WhatChat son los siguientes.
Conversación
El siguiente payload se devolverá para una conversación.
{
"additional_attributes": {
"browser": {
"device_name": "string",
"browser_name": "string",
"platform_name": "string",
"browser_version": "string",
"platform_version": "string"
},
"referer": "string",
"initiated_at": {
"timestamp": "iso-datetime"
}
},
"can_reply": "boolean",
"channel": "string",
"id": "integer",
"inbox_id": "integer",
"contact_inbox": {
"id": "integer",
"contact_id": "integer",
"inbox_id": "integer",
"source_id": "string",
"created_at": "datetime",
"updated_at": "datetime",
"hmac_verified": "boolean"
},
"messages": ["Array de objetos de mensaje"],
"meta": {
"sender": {
// Objeto Contacto
},
"assignee": {
// Objeto Usuario
}
},
"status": "string",
"unread_count": "integer",
"agent_last_seen_at": "unix-timestamp",
"contact_last_seen_at": "unix-timestamp",
"timestamp": "unix-timestamp",
"account_id": "integer"
}
Contacto
El siguiente payload se devolverá para un contacto.
{
"additional_attributes": "object",
"custom_attributes": "object",
"email": "string",
"id": "integer",
"identifier": "string o null",
"name": "string",
"phone_number": "string o null",
"thumbnail": "string"
}
Usuario
El siguiente payload se devolverá para un agente/admin.
{
"id": "integer",
"name": "string",
"available_name": "string",
"avatar_url": "string",
"availability_status": "string",
"thumbnail": "string"
}
Mensaje
El siguiente payload se devolverá para un mensaje.
{
"id": "integer",
"content": "string",
"account_id": "integer",
"inbox_id": "integer",
"message_type": "integer",
"created_at": "unix-timestamp",
"updated_at": "datetime",
"private": "boolean",
"status": "string",
"source_id": "string / null",
"content_type": "string",
"content_attributes": "object",
"sender_type": "string",
"sender_id": "integer",
"external_source_ids": "object",
"sender": {
"type": "string - contacto/usuario"
// Objeto Usuario o Contacto
}
}
Notificación
El siguiente payload se devolverá para una notificación.
{
"id": "integer",
"notification_type": "string",
"primary_actor_type": "string",
"primary_actor_id": "integer",
"primary_actor": {
"can_reply": "boolean",
"channel": "string",
"id": "integer",
"inbox_id": "integer",
"meta": {
"assignee": {
"id": "integer",
"name": "string",
"available_name": "string",
"avatar_url": "string",
"type": "user",
"availability_status": "string",
"thumbnail": "string"
},
"hmac_verified": "boolean"
},
"agent_last_seen_at": "unix-timestamp",
"contact_last_seen_at": "unix-timestamp",
"timestamp": "unix-timestamp",
},
"read_at": "unix-timestamp",
"secondary_actor": "object/null",
"created_at":"unix-timestamp",
"account_id": "integer",
"push_message_title": "string"
}
Identifier #
Cada evento tendrá un atributo identifier en el siguiente formato.
{
"identifier": "{\\"channel\\":\\"RoomChannel\\",\\"pubsub_token\\":\\"token\\",\\"account_id\\":id,\\"user_id\\":user_id}"
}
Mensaje #
Cada evento incluirá un atributo message que retorna el nombre del evento junto con los datos asociados. Para ver la lista de eventos, consulta la documentación a continuación.
Tipos de Eventos #
conversation.created #
Este evento se activa cuando se inicia una nueva conversación. Si se está suscribiendo al token PubSub del contacto, este evento solo incluirá datos relacionados con la sesión específica asociada con el token PubSub.
Disponible para: agente/admin, contacto
{
"message": {
"event": "conversation.created",
"data": {
// Objeto Conversación estará disponible aquí
}
}
}
conversation.read #
Este evento se activa y se envía a los agentes/admins que tienen acceso a la bandeja de entrada cuando un contacto ha leído un mensaje.
Disponible para: agente/admin
{
"message": {
"event": "conversation.read",
"data": {
// Objeto Conversación estará disponible aquí
}
}
}
message.created #
Este evento se activa y se envía a los agentes, admins y contactos cuando se crea un nuevo mensaje en una conversación a la que tienen acceso.
Disponible para: agente/admin, contacto
{
"message": {
"event": "message.created",
"data": {
// Objeto Mensaje estará disponible aquí
}
}
}
message.updated #
Este evento se activa y se envía a los agentes, admins y contactos cuando se actualiza un mensaje en una conversación a la que tienen acceso.
Disponible para: agente/admin, contacto
{
"message": {
"event": "message.updated",
"data": {
// Objeto Mensaje estará disponible aquí
}
}
}
conversation.status_changed #
Este evento se envía a los agentes, admins y contactos cuando se actualiza el estado de una conversación.
Disponible para: agente/admin, contacto
{
"message": {
"event": "conversation.status_changed",
"data": {
// Objeto Conversación estará disponible aquí
}
}
}
conversation.typing_on #
Este evento se envía a los agentes, admins y contactos cuando un contacto o un agente empieza a escribir una respuesta.
Disponible para: agente/admin, contacto
{
"message": {
"event": "conversation.typing_on",
"data": {
"conversation": {
// Objeto Conversación estará disponible aquí
},
"user": {
// Objeto Contacto / Agente, Admin estará disponible aquí.
},
"is_private": "boolean", // Indica si el agente está escribiendo una nota privada o no.
"account_id": "integer"
}
}
}
conversation.typing_off #
Este evento se envía a los agentes, admins y contactos cuando un contacto o un agente deja de escribir una respuesta.
Disponible para: agente/admin, contacto
{
"message": {
"event": "conversation.typing_off",
"data": {
"conversation": {
// Objeto Conversación estará disponible aquí
},
"user": {
// Objeto Contacto / Usuario estará disponible aquí.
},
"account_id": "integer"
}
}
}
assignee.changed #
Este evento se envía a los agentes/admins con acceso a una bandeja de entrada cuando se cambia el agente asignado.
Disponible para: agente/admin
{
"message": {
"event": "assignee.changed",
"data": {
// Objeto Conversación estará disponible aquí
}
}
}
team.changed #
Este evento se envía a los agentes/admins con acceso a una bandeja de entrada cuando se cambia el equipo asignado.
Disponible para: agente/admin
{
"message": {
"event": "team.changed",
"data": {
// Objeto Conversación estará disponible aquí
}
}
}
conversation.contact_changed #
Este evento se envía a los agentes/admins cuando se fusionan dos contactos y todas sus conversaciones se consolidan bajo un solo contacto.
Disponible para: agente/admin
{
"message": {
"event": "conversation.contact_changed",
"data": {
// Objeto Conversación estará disponible aquí
}
}
}
contact.created #
Este evento se envía a los agentes/admins cuando se crea un contacto.
Disponible para: agente/admin
{
"message": {
"event": "contact.created",
"data": {
// Objeto Contacto estará disponible aquí
}
}
}
contact.updated #
Este evento se envía a los agentes/admins cuando se actualiza un contacto.
Disponible para: agente/admin
{
"message": {
"event": "contact.updated",
"data": {
// Objeto Contacto estará disponible aquí
}
}
}
presence.update #
Disponible tanto para el agente como para el contacto, este evento proporciona actualizaciones en tiempo real sobre el estado de disponibilidad de los usuarios en el sistema. El evento entregado a los contactos no incluirá información sobre el estado de disponibilidad de otros contactos.
Disponible para: agente/admin
{
"message": {
"event": "presence.update",
"data": {
"account_id": "integer",
"users": {
"user-id": "string"
},
"contacts": {
"contact-id": "string"
}
}
}
}
notification_created #
Este evento se envía a los agentes/admins cuando se crea una notificación.
Disponible para: agente/admin
Que te pareció esta publicación?
-
Happy
-
Normal
-
Sad
