¿Cómo se establece una conexión WebSocket?
Los WebSockets establecen una conexión continua entre el cliente y el servidor, permitiendo la comunicación
bidireccional. La Plataforma utiliza esta conexión para proporcionar actualizaciones en tiempo real sobre eventos de la
plataforma. Para conectarse al WebSocket de la Plataforma, simplemente proporcione un token y siga las instrucciones de
configuración descritas en esta guía.
Observación: este recurso es experimental y la documentación puede cambiar en cada lanzamiento. Además, la
compatibilidad con versiones anteriores no puede garantizarse, por lo que es importante asegurarse de que esté
utilizando la versión más reciente de la implementación.
¿Por qué debo usar una conexión WebSocket? Una conexión WebSocket permite actualizaciones de datos en tiempo real, lo
que la hace ideal para clientes como un SDK cliente Android o iOS para la Plataforma. Esto ayuda a actualizar el panel
sin necesidad de recargar la página. En consecuencia, puede mejorar la experiencia del usuario y aumentar la
productividad del agente.
¿Cómo configurar una conexión WebSocket con la Plataforma? Para configurar una conexión WebSocket con la Plataforma,
debe iniciar una conexión con el token PubSub de autenticación proporcionado por la Plataforma. La URL para la conexión
es wss:///cable. Si está utilizando la Nube de la Plataforma, puede usar wss://app.plataforma.com/cable como URL.
Un token PubSub es un token utilizado para autenticar un cliente al conectarse a un servicio PubSub
(publicar-suscribir). El cliente debe presentar este token al servicio para establecer una conexión y comenzar a
publicar o suscribir mensajes.
Hay dos tipos de tokens PubSub disponibles en la Plataforma, como se describe a continuación:
- Token PubSub de usuario: Este token tiene privilegios de un agente/administrador y recibiría todos los eventos
enumerados posteriormente en la página. Puede obtener el token PubSub llamando a la API de Perfil.
- Token PubSub de contacto: La Plataforma genera un token PubSub exclusivo para cada sesión que un contacto posee.
Este token se puede usar 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 API públicas, el pubsub_token se incluye en la carga de respuesta. Este
token otorga acceso solo a eventos relacionados con la sesión actual, como: conversation.created,
conversation.status_changed, message.created, message.updated, conversation_typing_on, conversation_typing_off y
presence.update.
Consulte las API del cliente para crear integraciones orientadas al cliente en tiempo real utilizando la Plataforma.
Observación: este token puede cambiar regularmente según el tipo de instalación. Asegúrese de estar utilizando el token
más reciente.
¿Cómo conectarse al WebSocket de la Plataforma? Para conectarse al WebSocket de la Plataforma, use el comando subscribe
e incluya su pubSubToken, accountId y userId (si está utilizando un token de usuario) en la solicitud de conexión. Aquí
hay un ejemplo de cómo puede conectarse a la Plataforma.
// Agregue un método auxiliar para convertir JSON en una cadena
const stringify = (payload = {}) => JSON.stringify(payload);
const pubSubToken = "<contact/user-pub-sub-token>";
const accountId = "<your-account-id-in-integer>";
const userId = "<user-id-in-integer-if-using-user-token>";
const connection = new WebSocket(
"wss://app.plataforma.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 es del formato:
// {"command":"subscribe","identifier":"{\\"channel\\":\\"RoomChannel\\",\\"pubsub_token\\":\\"your-pubsub-token\\",\\"account_id\\": account_id_integer,\\"user_id\\":user_id_integer }"}
Publicando presencia en el servidor WebSocket Para mantener el estado de sus usuarios en línea en la Plataforma, puede
enviar un evento de actualización de presencia a la Plataforma cada 30 segundos. Esta acción mantendría al
agente/contacto en línea.
¿Cómo actualizar la presencia de un agente/administrador? Para actualizar la presencia de un agente o administrador,
envíe la siguiente carga al servidor:
const userPayload = stringify({
command: "message",
identifier: stringify({
channel: "RoomChannel",
pubsub_token: "<user-pubsub-token>",
account_id: accountId,
user_id: userId,
}),
data: stringify({ action: "update_presence" }),
});
connection.send(userPayload);
// La cadena esperada en connection.send es del formato:
// {"command":"message","identifier":"{\\"channel\\":\\"RoomChannel\\",\\"pubsub_token\\":\\"your-pubsub-token\\",\\"account_id\\": account_id_integer,\\"user_id\\":user_id_integer ","data":"{\\"action\\":\\"update_presence\\"}"}
¿Cómo actualizar la presencia de un contacto? Para actualizar la presencia de un contacto, envíe la siguiente carga al
servidor:
const agentPayload = stringify({
command: "message",
identifier: stringify({
channel: "RoomChannel",
pubsub_token: "<user-pubsub-token>",
}),
data: stringify({ action: "update_presence" }),
});
connection.send(agentPayload);
// La cadena esperada en connection.send es del formato:
// {"command":"message","identifier":"{\\"channel\\":\\"RoomChannel\\",\\"pubsub_token\\":\\"your-pubsub-token\\","data":"{\\"action\\":\\"update_presence\\"}"}
Carga útil del WebSocket Objetos Un evento puede contener cualquiera de los siguientes objetos como carga útil. Los
diferentes tipos de objetos admitidos en la Plataforma son los siguientes:
- Conversación
- Contacto
- Usuario
- Mensaje
- Notificación
Cada evento tendrá un atributo "Identifier" en el siguiente formato:
{
"identifier": "{\\"channel\\":\\"RoomChannel\\",\\"pubsub_token\\":\\"token\\",\\"account_id\\":id,\\"user_id\\":user_id}"
}
Cada evento incluirá un atributo "message" al que devolveremos el nombre del evento, así como los datos asociados a él.
Tipos de eventos Los diferentes tipos de eventos que pueden ocurrir en la Plataforma y sus descripciones son los
siguientes:
- conversation.created Este evento se desencadena cuando se inicia una nueva conversación. Si está suscrito al token
PubSub del contacto, este evento incluirá solo datos relacionados con la sesión específica asociada al token PubSub.
Disponible para: agente/administrador, contacto
{
"message": {
"event": "conversation.created",
"data": {
// Aquí estará disponible el objeto de conversación
}
}
}
- conversation.read Este evento se desencadena y se envía a los agentes/administradores que tienen acceso al buzón de
entrada cuando un contacto lee un mensaje.
Disponible para: agente/administrador
{
"message": {
"event": "conversation.read",
"data": {
// Aquí estará disponible el objeto de conversación
}
}
}
- message.created Este evento se desencadena y se envía a los agentes, administradores y contactos cuando se crea un
nuevo mensaje en una conversación a la que tienen acceso.
Disponible para: agente/administrador, contacto
{
"message": {
"event": "message.created",
"data": {
// Aquí estará disponible el objeto de mensaje
}
}
}
- message.updated Este evento se desencadena y se envía a los agentes, administradores y contactos cuando se actualiza
un mensaje en una conversación a la que tienen acceso.
Disponible para: agente/administrador, contacto
{
"message": {
"event": "message.updated",
"data": {
// Aquí estará disponible el objeto de mensaje
}
}
}
- conversation.status_changed Este evento se envía a los agentes, administradores y contactos cuando se actualiza el
estado de una conversación.
Disponible para: agente/administrador, contacto
{
"message": {
"event": "conversation.status_changed",
"data": {
// Aquí estará disponible el objeto de conversación
}
}
}
- conversation.typing_on Este evento se envía a los agentes, administradores y contactos cuando un contacto o agente
comienza a escribir una respuesta.
Disponible para: agente/administrador, contacto
{
"message": {
"event": "conversation.typing_on",
"data": {
"conversation": {
// Aquí estará disponible el objeto de conversación
},
"user": {
// Aquí estará disponible el objeto de contacto/agente
},
"is_private": "boolean", // Muestra si el agente está escribiendo una nota privada o no.
"account_id": "integer"
}
}
}
- conversation.typing_off Este evento se envía a los agentes, administradores y contactos cuando un contacto o agente
deja de escribir una respuesta.
Disponible para: agente/administrador, contacto
{
"message": {
"event": "conversation.typing_off",
"data": {
"conversation": {
// Aquí estará disponible el objeto de conversación
},
"user": {
// Aquí estará disponible el objeto de contacto/usuario
},
"account_id": "integer"
}
}
}
- assignee.changed Este evento se envía a los agentes/administradores con acceso a un buzón de entrada cuando se
cambia el agente asignado.
Disponible para: agente/administrador
{
"message": {
"event": "assignee.changed",
"data": {
// Aquí estará disponible el objeto de conversación
}
}
}
- team.changed Este evento se envía a los agentes/administradores con acceso a un buzón de entrada cuando se cambia el
equipo asignado.
Disponible para: agente/administrador
{
"message": {
"event": "team.changed",
"data": {
// Aquí estará disponible el objeto de conversación
}
}
}
- conversation.contact_changed Este evento se envía a los agentes/administradores cuando dos contactos se fusionan y
todas sus conversaciones se consolidan en un solo contacto.
Disponible para: agente/administrador
{
"message": {
"event": "conversation.contact_changed",
"data": {
// Aquí estará disponible el objeto de conversación
}
}
}
- contact.created Este evento se envía a los agentes/administradores cuando se crea un contacto.
Disponible para: agente/administrador
{
"message": {
"event": "contact.created",
"data": {
// Aquí estará disponible el objeto de contacto
}
}
}
- contact.updated Este evento se envía a los agentes/administradores cuando se actualiza un contacto.
Disponible para: agente/administrador
{
"message": {
"event": "contact.updated",
"data": {
// Aquí estará disponible el objeto de contacto
}
}
}
- 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/administrador
{
"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/administradores cuando se crea una notificación.
Disponible para: agente/administrador