Os WebSockets estabelecem uma conexão contínua entre o cliente e o servidor, permitindo a comunicação bidirecional. O Chatwoot utiliza essa conexão para fornecer atualizações em tempo real sobre eventos da plataforma. Para se conectar ao WebSocket do Chatwoot, basta fornecer um token e seguir as instruções de configuração descritas neste guia.
Observação: Este recurso é experimental e a documentação pode mudar a cada lançamento. Além disso, a compatibilidade com versões anteriores não pode ser garantida, por isso é importante garantir que você esteja usando a versão mais recente da implementação.
Por que devo usar uma conexão WebSocket?
Uma conexão WebSocket permite atualizações de dados em tempo real, tornando-a ideal para clientes como um SDK de cliente Android ou iOS para o Chatwoot. Isso ajuda a atualizar o painel sem a necessidade de recarregar a página. Portanto, pode aprimorar a experiência do usuário e aumentar a produtividade do agente.
Como configurar uma conexão WebSocket com o Chatwoot?
Para configurar uma conexão WebSocket com o Chatwoot, você precisa iniciar uma conexão com o token de autenticação PubSub fornecido pelo Chatwoot. A URL da conexão é wss://<your-installation-url>/cable. Se estiver usando o Chatwoot Cloud, você pode usar wss://app.chatwoot.com/cable como URL.
Um token PubSub é usado para autenticar um cliente ao se conectar a um serviço PubSub (publicar-assinar). O cliente deve apresentar esse token ao serviço para estabelecer uma conexão e começar a publicar ou assinar mensagens.
Existem dois tipos de tokens PubSub disponíveis no Chatwoot, conforme listados abaixo.
-
Token PubSub do Usuário: Este token possui os privilégios de um agente/administrador e receberia todos os eventos listados posteriormente na página. Você pode obter o token PubSub chamando a API de Perfil.
-
Token PubSub do Contato: O Chatwoot gera um token PubSub exclusivo para cada sessão de um contato. Este token pode ser usado para se conectar ao WebSocket e receber atualizações em tempo real para a mesma sessão. Quando um contato é criado por meio das APIs públicas, o
pubsub_tokené incluído no payload da resposta. Este token concede acesso apenas a eventos relacionados à sessão atual, comoconversation.created,conversation.status_changed,message.created,message.updated,conversation_typing_on,conversation_typing_offepresence.update.
Consulte as APIs do cliente para criar integrações em tempo real com o cliente usando o Chatwoot.
Observação: Este token pode ser rotacionado regularmente, dependendo do tipo de instalação. Certifique-se de usar o token mais recente.
Como se conectar ao Chatwoot WebSocket?
Para se conectar ao Chatwoot WebSocket, use o comando subscribe e inclua seu pubSubToken, accountId e userId (se estiver usando um token de usuário) na solicitação de conexão. Aqui está um exemplo de como você pode se conectar ao Chatwoot.
// Adicione um método auxiliar para converter JSON em uma string
const stringify = (payload = {}) => JSON.stringify(payload);
const pubSubToken = "<contato/usuário-pub-sub-token>";
const accountId = "<id-da-sua-conta-em-número-inteiro>";
const userId = "<id-do-usuário-em-número-inteiro-se-estiver-usando-token-do-usuário>";
const connection = new WebSocket(
"wss://app.chatwoot.com/cable"
);
connection.send(
stringify({
command: "subscribe",
identifier: stringify({
channel: "RoomChannel",
pubsub_token: pubSubToken,
account_id: accountId,
user_id: userId,
}),
})
);
// A string esperada em connection.send tem o formato:
// {"command":"subscribe","identifier":"{\\"channel\\":\\"RoomChannel\\",\\"pubsub_token\\":\\"your-pubsub-token\\",\\"account_id\\": account_id_integer,\\"user_id\\":user_id_integer }"}
Publicando presença no servidor WebSocket
Para manter o status dos seus usuários online no Chatwoot, você pode enviar um evento de atualização de presença para o Chatwoot a cada 30 segundos. Essa ação manterá o status do agente/contato online.
Como atualizar a presença de um agente/administrador?
Para atualizar a presença de um agente ou administrador, envie o seguinte payload para o 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);
// A string esperada em connection.send tem o formato:
// {"command":"message","identifier":"{\\"channel\\":\\"RoomChannel\\",\\"pubsub_token\\":\\"your-pubsub-tokpt-BR\\",\\"id_da_conta\\": id_da_conta_inteiro,\\"id_do_usuário\\": id_do_usuário_inteiro ","dados":"{\\"ação\\":\\"atualizar_presença\\"}"}
Como atualizar a presença de um contato?
Para atualizar a presença de um contato, envie o seguinte payload para o servidor:
const agentPayload = stringify({
comando: "mensagem",
identificador: stringify({
canal: "CanalDaSala",
pubsub_token: "<token-do-pubsub-do-usuário>",
}),
dados: stringify({ação: "atualizar_presença" }),
});
conexão.send(agentPayload);
// A string esperada em connection.send tem o formato:
// {"command":"message","identifier":"{\\"channel\\":\\"RoomChannel\\",\\"pubsub_token\\":\\"your-pubsub-token\\","data":"{\\"action\\":\\"update_presence\\"}"}
Payload do WebSocket
Objects
Um evento pode conter qualquer um dos seguintes objetos como payload. Os diferentes tipos de objetos suportados no Chatwoot são os seguintes:
Conversa
O seguinte payload será retornado para uma conversa.
{
"additional_attributes": {
"browser": {
"device_name": "string",
"nome_do_navegador": "string",
"nome_da_plataforma": "string",
"versão_do_navegador": "string",
"versão_da_plataforma": "string"
},
"referente": "string",
"iniciado_em": {
"carimbo_de_hora": "iso-data-hora"
}
},
"pode_responder": "booleano",
"canal": "string",
"id": "inteiro",
"id_caixa_de_entrada": "inteiro",
"caixa_de_entrada_do_contato": {
"id": "inteiro",
"id_contato": "inteiro",
"id_caixa_de_entrada": "inteiro",
"id_da_caixa_de_entrada": "inteiro",
"id_fonte": "string",
"criado_em": "data/hora",
"atualizado_em": "data/hora",
"hmac_verificado": "booleano"
},
"mensagens": ["Matriz de objetos de mensagem"],
"meta": {
"sender": {
// Objeto de Contato
},
"assignee": {
// Objeto de Usuário
}
},
"status": "string",
"unread_count": "integer",
"agent_last_seen_at": "unix-timestamp",
"contact_last_seen_at": "unix-timestamp",
"timestamp": "unix-timestamp",
"account_id": "integer"
}
Contato
O seguinte payload será retornado para um contato.
{
"additional_attributes": "object",
"custom_attributes": "object",
"email": "string",
"id": "integer",
"identifier": "string ou null",
"name": "string",
"phone_number": "string ou nulo",
"thumbnail": "string"
}
Usuário
O seguinte payload será retornado para um agente/administrador.
{
"id": "inteiro",
"nome": "string",
"available_name": "string",
"avatar_url": "string",
"availability_status": "string",
"thumbnail": "string"
}
Mensagem
O seguinte payload será retornado para uma mensagem.
{
"id": "inteiro",
"content": "string",
"account_id": "inteiro",
"inbox_id": "inteiro",
"message_type": "inteiro",
"created_at": "unix-timestamp",
"updated_at": "data/hora",
"private": "booleano",
"status": "string",
"source_id": "string / null",
"content_type": "string",
"content_attributes": "objeto",
"sender_type": "string",
"sender_id": "inteiro",
"external_source_ids": "objeto",
"sender": {
"type": "string - contato/usuário"
// Objeto Usuário ou Contato
}
}
Notificação
O seguinte payload será retornado para uma notificação.
{
"id": "inteiro",
"notification_type": "string",
"primary_actor_type": "string",
"primary_actor_id": "inteiro",
"primary_actor": {
"can_reply": "booleano",
"channel": "string",
"id": "inteiro",
"inbox_id": "inteiro",
"meta": {
"assignee": {
"id": "inteiro",
"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": "inteiro",
"push_message_title": "string"
}
Identificador
Cada evento terá um atributo identificador no seguinte formato.
{
"identificador": "{\\"canal\\":\\"ChannelRoomChannel\\",\\"pubsub_token\\":\\"token\\",\\"id_da_conta\\":id,\\"id_do_usuário\\":id_do_usuário}"
}
Mensagem
Cada evento incluirá um atributo mensagem, que retorna o nome do evento, bem como os dados associados a ele. Para ver a lista de eventos, consulte a documentação abaixo.
Tipos de Eventos
conversation.created
Este evento é acionado quando uma nova conversa é iniciada. Se estiver assinando o token PubSub do contato, este evento incluirá apenas dados relacionados à sessão específica associada ao token PubSub.
Disponível para: agente/administrador, contato
{
"message": {
"event": "conversation.created",
"data": {
// ConversatO objeto ion estará disponível aqui
}
}
}
conversation.read
Este evento é acionado e enviado aos agentes/administradores que têm acesso à caixa de entrada quando um contato lê uma mensagem.
Disponível para: agente/administrador
{
"message": {
"event": "conversation.read",
"data": {
// O objeto Conversation estará disponível aqui
}
}
}
message.created
Este evento é acionado e enviado aos agentes, administradores e contatos quando uma nova mensagem é criada em uma conversa à qual eles têm acesso.
Disponível para: agente/administrador, contato
{
"message": {
"event": "message.created",
"data": {
// O objeto Message estará disponível aqui
}
}
}
message.updated
Este evento é acionado e enviado aos agentes, administradores e contatos quando uma mensagem é atualizada em uma conversa à qual eles têm acesso.
Disponível para: agente/administrador, contato
{
"message": {
"event": "message.updated",
"data": {
// O objeto Message estará disponível aqui
}
}
}
conversation.status_changed
Este evento é enviado aos agentes, administradores e contatos quando o status de uma conversa é atualizado.
Disponível para: agente/administrador, contato
{
"message": {
"event": "conversation.status_changed",
"data": {
// O objeto Conversation estará disponível aqui
}
}
}
conversation.typing_on
Este evento é enviado aos agentes, administradores e contatos quando um contato ou agente começa a digitar uma resposta.
Disponível para: agente/administrador, contato
{
"message": {
"event": "conversation.typing_on",
"data": {
"conversation": {
// O objeto Conversation estará disponível aqui
},
"user": {
// O objeto Contato/Agente,Administrador e Usuário estará disponível aqui.
},
"is_private": "boolean", // Mostra se o agente está digitando uma nota privada ou não.
"account_id": "integer"
}
}
}
conversation.typing_off
Este evento é enviado aos agentes, administradores e contatos quando um contato ou agente termina de digitar uma resposta.
Disponível para: agente/administrador, contato
{
"message": {
"event": "conversation.typing_off",
"data": {
"conversation": {
// O objeto Conversa estará disponível aqui
},
"user": {
// O objeto Contato/Usuário estará disponível aqui.
},
"account_id": "integer"
}
}
}
assignee.changed
Este evento é enviado aos agentes/administradores com acesso a uma caixa de entrada quando o agente atribuído é alterado.
Disponível para: agente/administrador
{
"message": {
"event": "assignee.changed",
"data": {
// O objeto de conversa estará disponível aqui
}
}
}
team.changed
Este evento é enviado aos agentes/administradores com acesso a uma caixa de entrada quando a equipe atribuída é alterada.
Disponível para: agente/administrador
{
"message": {
"event": "team.changed",
"data": {
// O objeto de conversa estará disponível aqui
}
}
}
conversation.contact_changed
Este evento é enviado aos agentes/administradores quando dois contatos são mesclados e todas as suas conversas são consolidadas em um único contato.
Disponível para: agente/administrador
{
"message": {
"event": "conversation.contact_changed",
"data": {
// O objeto de conversa estará disponível aqui
}
}
}
contact.created
Este evento é enviado aos agentes/administradores quando um contato é criado.
Disponível para: agente/administrador
{
"message": {
"event": "contact.created",
"data": {
// O objeto de contato estará disponível aqui
}
}
}
contact.updated
Este evento é enviado aos agentes/administradores quando um contato é atualizado.
Disponível para: agente/administrador
{
"message": {
"event": "contact.updated",
"data": {
// O objeto de contato estará disponível aqui
}
}
}
presence.update
Disponível tanto para o agente quanto para o contato, este evento fornece atualizações em tempo real sobre o status de disponibilidade dos usuários no sistema. O evento entregue aos contatos não incluirá informações sobre o status de disponibilidade de outros contatos.
Disponível para: agente/administrador
{
"message": {
"event": "presence.update",
"data": {
"account_id": "integer",
"users": {
"user-id": "string"
},
"contacts": {
"contact-id": "string"
}
}
}
}
notification_created
Este evento é enviado aos agentes/administradores quando uma notificação é criada.
Disponívelrótulo para: agente/administrador