Use este guia quando você precisar configurar, entender ou validar **Como configurar uma conexão WebSocket** na IAra. ## Antes de começar na IAra - Confirme que seu usuário tem permissão para acessar a área citada no artigo. - Faça a configuração primeiro em um cenário de teste, sempre que o recurso afetar atendimentos reais. - Se o fluxo envolver WhatsApp, Meta, Twilio, e-mail, domínio, SAML, API ou outro provedor externo, confirme as credenciais e permissões antes de iniciar. ## Guia detalhado WebSockets estabelecem uma conexão contínua entre a pessoa atendida e o servidor, permitindo a comunicação bidirecional. IAra utiliza esta conexão para fornecer atualizações em tempo real sobre eventos da plataforma. Para se conectar a IAra WebSocket, 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 cliente Android ou iOS para IAra. Isso ajuda a atualizar o painel sem a necessidade de recarregar a página. Conseqüentemente, pode aprimorar a experiência do usuário e melhorar a produtividade do agente. ## Como configurar uma conexão WebSocket com IAra? Para configurar uma conexão WebSocket com IAra, você precisa iniciar uma conexão com o token PubSub de autenticação fornecido pela IAra. Use `wss://app.digi2b.com/cable` como URL da conexão. > Um token PubSub é um token usado para autenticar um cliente ao se conectar a um serviço PubSub (publicar-assinar). A pessoa atendida deve apresentar este 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 na IAra, conforme listado abaixo. 1. **Token PubSub do usuário**: Este token tem 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 . 2. **Token PubSub de contato**: IAra gera um token PubSub exclusivo para cada sessão que um contato possui. Este token pode ser usado para conectar-se ao WebSocket e receber atualizações em tempo real para a mesma sessão. Quando um contato é criado por meio de APIs públicas, o `pubsub_token` é incluído na carga útil da resposta. Este token concede acesso apenas a eventos relacionados à sessão atual, como `conversation.created`,  `conversation.status_changed`, `message.created`, `message.updated`, `conversation_typing_on`, `conversation_typing_off` e `presence.update`. Consulte  para criar integrações voltadas para a pessoa atendida em tempo real usando a IAra. **Observação**: Este token pode ser alternado regularmente com base no seu tipo de instalação. Certifique-se de estar usando o token mais recente. ### Como se conectar a IAra WebSocket? Para se conectar a IAra 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 a IAra. ``` //Adiciona um método auxiliar para converter JSON em uma string const stringify = (carga útil = {}) => JSON.stringify (carga útil); const pubSubToken = ""; const accountId = ""; const userId = ""; conexão const = novo WebSocket( "wss://app.digi2b.com/cable" ); conexão.send( stringificar({ comando: "inscrever-se", identificador: stringify({ canal: "RoomChannel", pubsub_token: pubSubToken, ID_da_conta: id da conta, user_id: ID do usuário, }), }) ); // A string esperada em connection.send tem o formato: // {"command":"subscribe","identifier":"{\\"canal\\":\\"RoomChannel\\",\\"pubsub_token\\":\\"seu-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 na IAra, você pode enviar um evento de atualização de presença para a IAra a cada 30 segundos. Esta ação manteria 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 a seguinte carga ao servidor: ``` const userPayload = stringify({ comando: "mensagem", identificador: stringify({ canal: "RoomChannel", pubsub_token: "", ID_da_conta: id da conta, user_id: ID do usuário, }), dados: stringify({ ação: "update_presence" }), }); conexão.send(userPayload); // A string esperada em connection.send tem o formato: // {"command":"message","identifier":"{\\"canal\\":\\"RoomChannel\\",\\"pubsub_token\\":\\"seu-pubsub-token\\",\\"account_id\\": account_id_integer,\\"user_id\\":user_id_integer ","dados":"{\\"ação\\":\\"update_presence\\"}"} ``` **Como atualizar a presença de um contato?** Para atualizar a presença de um contato, envie a seguinte carga ao servidor: ``` const agentePayload = stringify({ comando: "mensagem", identificador: stringify({ canal: "RoomChannel", pubsub_token: "", }), dados: stringify({ ação: "update_presence" }), }); conexão.send(agentePayload); // A string esperada em connection.send tem o formato: // {"command":"message","identifier":"{\\"channel\\":\\"RoomChannel\\",\\"pubsub_token\\":\\"your-pubsub-token\\","data":"{\\"action\\":\\"update_presence\\"}"} ``` ## Carga útil do WebSocket ### Objetos Um evento pode conter qualquer um dos seguintes objetos como carga útil. Diferentes tipos de objetos suportados na IAra são os seguintes. **Conversa** A seguinte carga útil será retornada para uma conversa. ``` { "atributos_adicionais": { "navegador": { "nome_do_dispositivo": "string", "nome_do_navegador": "string", "nome_plataforma": "string", "versão_do_navegador": "string", "versão_plataforma": "string" }, "referente": "string", "iniciado_em": { "timestamp": "iso-datetime" } }, "can_reply": "booleano", "canal": "string", "id": "inteiro", "inbox_id": "inteiro", "contato_inbox": { "id": "inteiro", "contact_id": "inteiro", "inbox_id": "inteiro", "source_id": "string", "criado_em": "datahora", "atualizado_at": "datahora", "hmac_verified": "booleano" }, "messages": ["Matriz de objetos de mensagem"], "meta": { "remetente": { // Objeto de contato }, "responsável": { // Objeto de usuário } }, "status": "string", "unread_count": "inteiro", "agent_last_seen_at": "timestamp unix", "contact_last_seen_at": "timestamp unix", "timestamp": "timestamp unix", "account_id": "inteiro" } ``` **Contato** A seguinte carga útil será retornada para um contato. ``` { "atributos_adicionais": "objeto", "custom_attributes": "objeto", "e-mail": "string", "id": "inteiro", "identificador": "string ou nulo", "nome": "string", "phone_number": "string ou nulo", "miniatura": "string" } ``` **Usuário** A seguinte carga útil será retornada para um agente/administrador. ``` { "id": "inteiro", "nome": "string", "nome_disponível": "string", "avatar_url": "string", "availability_status": "string", "miniatura": "string" } ``` **Mensagem** A seguinte carga útil será retornada para uma mensagem. ``` { "id": "inteiro", "conteúdo": "string", "account_id": "inteiro", "inbox_id": "inteiro", "message_type": "inteiro", "created_at": "timestamp unix", "atualizado_at": "datahora", "privado": "booleano", "status": "string", "source_id": "string/nulo", "content_type": "string", "content_attributes": "objeto", "sender_type": "string", "sender_id": "inteiro", "external_source_ids": "objeto", "remetente": { "type": "string - contato/usuário" // Objeto de usuário ou contato } } ``` **Notificação** A seguinte carga útil será retornada para uma notificação. ``` { "id": "inteiro", "notification_type": "string", "primary_actor_type": "string", "primary_actor_id": "inteiro", "ator_primário": { "can_reply": "booleano", "canal": "string", "id": "inteiro", "inbox_id": "inteiro", "meta": { "responsável": { "id": "inteiro", "nome": "string", "nome_disponível": "string", "avatar_url": "string", "tipo": "usuário", "availability_status": "string", "miniatura": "string" }, "hmac_verified": "booleano" }, "agent_last_seen_at": "timestamp unix", "contact_last_seen_at": "timestamp unix", "timestamp": "timestamp unix", }, "read_at": "timestamp unix", "secondary_actor": "objeto/nulo", "created_at":"carimbo de data e hora unix", "account_id": "inteiro", "push_message_title": "string" } ``` ### Identificador Cada evento terá um atributo `identificador` no formato a seguir. ``` { "identifier": "{\\"canal\\":\\"RoomChannel\\",\\"pubsub_token\\":\\"token\\",\\"account_id\\":id,\\"user_id\\":user_id}" } ``` ### Mensagem Cada evento incluirá um atributo `message` que retornaremos 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 ### conversa.criada Este evento é acionado quando uma nova conversa é iniciada. Se estiver assinando o token PubSub do contato, esse evento incluirá apenas dados relacionados à sessão específica associada ao token PubSub. **Disponível para**: agente/administrador, contato ``` { "mensagem": { "evento": "conversa.criada", "dados": { //O objeto Conversa estará disponível aqui } } } ``` ### conversa.ler 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 ``` { "mensagem": { "evento": "conversa.leitura", "dados": { //O objeto Conversa estará disponível aqui } } } ``` ### mensagem.criada 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 ``` { "mensagem": { "evento": "mensagem.criada", "dados": { //O objeto mensagem estará disponível aqui } } } ``` ### mensagem.atualizada 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 ``` { "mensagem": { "evento": "mensagem.atualizada", "dados": { //O objeto mensagem estará disponível aqui } } } ``` ### conversação.status_changed Este evento é enviado aos agentes, administradores e contatos quando o status de uma conversa é atualizado. **Disponível para**: agente/administrador, contato ``` { "mensagem": { "evento": "conversação.status_changed", "dados": { //O objeto Conversa estará disponível aqui } } } ``` ### conversa.digitando_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 ``` { "mensagem": { "evento": "conversação.typing_on", "dados": { "conversa": { //O objeto Conversa estará disponível aqui }, "usuário": { // Contato / Agente, objeto Usuário Administrador estará disponível aqui. }, "is_private": "boolean", // Mostra se o agente está digitando uma nota privada ou não. "account_id": "inteiro" } } } ``` ### conversação.typing_off Este evento é enviado aos agentes, administradores, contatos quando um contato ou agente termina de digitar uma resposta. **Disponível para**: agente/administrador, contato ``` { "mensagem": { "evento": "conversação.typing_off", "dados": { "conversa": { //O objeto Conversa estará disponível aqui }, "usuário": { //O objeto Contato/Usuário estará disponível aqui. }, "account_id": "inteiro" } } } ``` ### responsável.alterado Este evento é enviado aos agentes/administradores com acesso a uma caixa de entrada quando o agente atribuído é alterado. **Disponível para**: agente/administrador ``` { "mensagem": { "evento": "designado.alterado", "dados": { //O objeto Conversa estará disponível aqui } } } ``` ### equipe.alterada Este evento é enviado aos agentes/administradores com acesso a uma caixa de entrada quando a equipe designada é alterada. **Disponível para**: agente/administrador ``` { "mensagem": { "evento": "equipe.alterada", "dados": { //O objeto Conversa estará disponível aqui } } } ``` ### conversação.contact_changed Este evento é enviado aos agentes/administradores quando dois contatos são mesclados e todas as suas conversas são consolidadas em um contato. **Disponível para**: agente/administrador ``` { "mensagem": { "evento": "conversação.contact_changed", "dados": { //O objeto Conversa estará disponível aqui } } } ``` ### contato.criado Este evento é enviado aos agentes/administradores quando um contato é criado. **Disponível para**: agente/administrador ``` { "mensagem": { "evento": "contato.criado", "dados": { //O objeto de contato estará disponível aqui } } } ``` ### contato.atualizado Este evento é enviado aos agentes/administradores quando um contato é atualizado. **Disponível para**: agente/administrador ``` { "mensagem": { "evento": "contato.atualizado", "dados": { //O objeto de contato estará disponível aqui } } } ``` ###presença.atualização 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 ``` { "mensagem": { "evento": "presença.update", "dados": { "account_id": "inteiro", "usuários": { "ID do usuário": "string" }, "contatos": { "ID de contato": "string" } } } } ``` ###notificação_criada Este evento é enviado aos agentes/administradores quando uma notificação é criada. **Disponível para**: agente/administrador --- ## Como validar na IAra 1. Execute o fluxo em uma conta ou conversa de teste. 2. Confirme se o resultado aparece para o agente, gestor ou cliente exatamente como esperado. 3. Revise se o nome da caixa, time, etiqueta, assistente ou integração está claro para o restante da equipe. ## Problemas comuns - Usuário sem permissão para acessar a configuração. - Nome de tela diferente entre versões ou contas. - Recurso dependente de plano, provedor externo ou habilitação pela Digi2B. - Falta de teste em conversa realista antes de liberar para a equipe. ## Checklist final - [ ] Configuração revisada por um administrador. - [ ] Teste realizado com dado ou conversa controlada. - [ ] Impacto para agentes e gestores entendido. - [ ] Artigos relacionados revisados para evitar links quebrados.