Central de Ajuda Iara Conversas

Como configurar uma conexão WebSocket

Open in
View as Markdown Open in ChatGPT Open in Claude
Suporte

Suporte

Última atualização em Jun 1, 2026

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 = "<contato/user-pub-sub-token>";
const accountId = "<id-da-sua-conta-em-inteiro>";
const userId = "<user-id-in-integer-if-using-user-token>";
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: "<user-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: "<user-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.