Guia do WebChat

Como instalar o chat no seu site, identificar clientes logados com um JWT assinado no seu servidor e como a sessão pública do visitante funciona.

O WebChat é um chat que você instala no seu site. As conversas chegam à caixa de entrada da Vozko como as dos outros canais, e o agente de IA ou o fluxo configurado no chat pode responder sozinho.

Cada chat (na API, widget) tem uma chave pública, que vai no código de instalação, a lista de sites permitidos e, opcionalmente, um segredo de identidade, com que o seu servidor assina quem é o cliente logado.

As rotas estão no grupo WebChat da Referência da API. As rotas de configuração usam o token de login; as rotas da sessão do visitante são públicas e só respondem à janela do chat.

Como funciona

  1. O seu site carrega o script loader.js com a chave pública do chat.
  2. O script desenha o botão e abre a janela do chat num iframe servido pela API, em /public/webchat/{publicKey}/frame. A janela só abre nos sites permitidos.
  3. A janela abre uma sessão para o visitante e recebe um token de sessão, que vale 30 dias e fica no navegador.
  4. O visitante conversa pela janela; as respostas chegam em tempo real.

Você só escreve o passo 1 e, se quiser identificar clientes logados, o JWT de identidade. Os passos seguintes são feitos pela janela do chat.

Criar o chat

POST /webchat/widgets cria o chat. A resposta traz publicKey, loaderUrl e snippet, o código pronto para colar no site.

CampoRegra
nameObrigatório, até 80 caracteres.
allowedOriginsObrigatório, até 20 sites. Cada um é uma origem exata (https://www.exemplo.com.br) ou um curinga de subdomínios (https://*.exemplo.com.br). http só para localhost.
identityModeoff (padrão), optional ou required. Com optional ou required, o chat ganha um segredo de identidade.
intakeName, intakeEmail, intakePhonehidden, optional ou required: o que o formulário inicial pede.
privacyPolicyUrlEndereço https. Com ele, o formulário inicial exige o aceite da política.
defaultCountryCodeDDI usado nos telefones sem DDI, de 1 a 3 dígitos. Padrão 55.
allowHumanRequestMostra a opção de falar com uma pessoa.
allowAttachmentsDeixa o visitante enviar arquivos.
agentId, workflowId, pipelineId, departmentIdQuem responde e para onde vão as conversas. Precisam ser deste workspace (422 reference_not_in_workspace).

Instalar no site

Cole o snippet do chat antes do fechamento de body:

<script async src="https://api.vozkoia.com/public/webchat/loader.js" data-key="CHAVE_PUBLICA"></script>

O script lê, ao carregar, o objeto global window.VozkoChat. Defina-o antes do script quando precisar de alguma destas opções:

PropriedadePara que serve
identityO JWT de identidade do cliente logado. Veja abaixo.
titleO título do iframe, para leitores de tela. Padrão Chat.

Depois de carregar, o script acrescenta ao mesmo objeto os métodos open() e close(), que abrem e fecham a janela.

<script>
  window.VozkoChat = { identity: "JWT_GERADO_NO_SEU_SERVIDOR" };
</script>
<script async src="https://api.vozkoia.com/public/webchat/loader.js" data-key="CHAVE_PUBLICA"></script>

Identificar clientes logados

Sem identidade, cada navegador é um visitante anônimo. Com um JWT assinado pelo seu servidor, o visitante passa a ser o seu cliente, o mesmo em qualquer aparelho, e o formulário inicial usa os dados do token no lugar do que a pessoa digitaria.

identityModeSem identityCom identity válidoCom identity inválido ou vencido
offVisitante anônimo.O token é ignorado.O token é ignorado.
optionalVisitante anônimo.Cliente identificado.401 identity_invalid ou 401 identity_expired.
required403 identity_required.Cliente identificado.401 identity_invalid ou 401 identity_expired.

O segredo

GET /webchat/widgets/{id}/identity-secret devolve o segredo em identitySecret. POST na mesma rota gera um segredo novo, e os JWTs assinados com o anterior deixam de valer na hora. Guarde o segredo só no servidor: nunca no navegador nem no aplicativo.

O token

Um JWT no formato compacto (cabeçalho.conteúdo.assinatura, cada parte em base64url sem =), com estas regras:

ParteRegra
Cabeçalhoalg igual a HS256.
AssinaturaHMAC-SHA256 de cabeçalho.conteúdo, com a chave igual ao texto do segredo, exatamente como a API devolve (não decodifique o segredo).
subObrigatório. O id do cliente no seu sistema, como texto (um número é recusado), até 128 bytes. É o que identifica o cliente entre aparelhos.
expObrigatório, em segundos Unix. No máximo 24 horas à frente.
iat, nbfOpcionais. Não podem estar no futuro.
name, email, phoneOpcionais. Atualizam os dados do visitante. Um telefone sem DDI recebe o defaultCountryCode do chat; um telefone que não é válido é ignorado.
TamanhoAté 4 KB.

A API tolera até 2 minutos de diferença de relógio em exp, iat e nbf.

Exemplo em Node.js, sem bibliotecas:

import { createHmac } from "node:crypto";

const base64url = (value) => Buffer.from(JSON.stringify(value)).toString("base64url");

export function identityToken(secret, customer) {
  const header = base64url({ alg: "HS256", typ: "JWT" });
  const payload = base64url({
    sub: String(customer.id),
    name: customer.name,
    email: customer.email,
    phone: customer.phone,
    iat: Math.floor(Date.now() / 1000),
    exp: Math.floor(Date.now() / 1000) + 3600,
  });
  const signature = createHmac("sha256", secret).update(`${header}.${payload}`).digest("base64url");
  return `${header}.${payload}.${signature}`;
}

Gere o token a cada página servida a um cliente logado e entregue-o em window.VozkoChat.identity. Uma biblioteca de JWT também serve, desde que use HS256 e o segredo como texto.

A sessão do visitante

As rotas abaixo são as que a janela do chat usa. Elas só respondem a pedidos da própria janela (mesma origem da API); um pedido de outro site recebe 403 cross_site. As rotas de /session exigem o cabeçalho Authorization: Bearer com o token da sessão do visitante; o token de login do painel não é aceito.

RotaO que faz
POST /public/webchat/{publicKey}/challengeDevolve um desafio anti-robô (prova de trabalho com SHA-256) que vale 2 minutos e uma única vez.
POST /public/webchat/{publicKey}/sessionAbre ou retoma a sessão. Com token válido, retoma o mesmo visitante; com identity, identifica o cliente; senão, exige o desafio resolvido (challengeToken e nonce). Devolve o token da sessão, a aparência do chat e o que falta no formulário inicial.
POST /public/webchat/session/intakeEnvia o formulário inicial: name, email, phone e consent, conforme o chat pede. Um telefone liga o visitante ao lead com o mesmo número.
GET /public/webchat/session/messagesHistórico do visitante, da mais antiga à mais nova, só com o que o cliente pode ver. before e after (RFC 3339) paginam.
POST /public/webchat/session/messagesEnvia texto (até 2.000 caracteres) ou a escolha de um botão oferecido (selectionId). clientMessageId, de 8 a 64 caracteres, torna o envio idempotente.
POST /public/webchat/session/mediaEnvia um arquivo (multipart/form-data com file e clientMessageId), se o chat aceita anexos: JPEG, PNG, WebP, GIF ou PDF, até 10 MB, com o tipo conferido pelo conteúdo.
POST /public/webchat/session/handoffPede atendimento humano, se o chat oferece: pausa a automação e passa a conversa para a fila do departamento do chat.
POST /public/webchat/session/typingAvisa aos atendentes que o visitante está digitando (typing).
GET /public/webchat/session/streamEventos em tempo real (Server-Sent Events).

Enquanto o formulário inicial tem campos obrigatórios ou o aceite da política sem resposta, enviar mensagens ou arquivos responde 409 intake_pending.

Eventos em tempo real

O fluxo de eventos é lido com fetch, com o token no cabeçalho, nunca na URL.

EventoDados
messageUma mensagem nova: id, author (visitor, team ou assistant), text, media, options, quote e createdAt.
typingA equipe está ou não digitando.
statusstate human (a conversa passou para uma pessoa) ou blocked (o visitante foi bloqueado).
pingA cada 20 segundos.

A conexão fecha depois de 30 minutos; a janela reconecta e busca o que perdeu com GET /public/webchat/session/messages?after=. Cada visitante tem no máximo 3 conexões ao mesmo tempo.

Erros da sessão

As recusas trazem um code estável:

StatusCódigoQuando
400challenge_invalid, challenge_expired, challenge_unsolved, challenge_reusedDesafio anti-robô inválido, vencido, errado ou já usado.
400client_message_id_invalidclientMessageId fora de 8 a 64 caracteres.
401session_invalid, session_expiredToken da sessão ausente, inválido ou vencido.
401identity_invalid, identity_expiredJWT de identidade inválido ou vencido.
403cross_sitePedido fora da janela do chat.
403origin_not_allowedO site não está entre os sites permitidos.
403identity_requiredO chat só aceita clientes identificados.
403visitor_blockedO visitante foi bloqueado pela equipe.
403attachments_disabled, human_request_disabledO chat não aceita anexos ou não oferece atendimento humano.
404widget_not_found, widget_unavailableChat inexistente, removido ou pausado.
409intake_pendingFalta responder o formulário inicial.
413attachment_too_largeArquivo maior que 10 MB.
415attachment_type_refusedTipo de arquivo não aceito.
422field_required, name_invalid, email_invalid, phone_invalid, consent_requiredRespostas do formulário inicial.
422message_empty, message_too_long, option_not_offeredMensagem vazia, longa demais ou escolha que não foi oferecida.
429rate_limitedLimite de novas sessões por IP e por chat, de mensagens ou de conexões.
503challenge_unavailableA conferência do desafio está indisponível. Tente de novo em instantes.

Rotas de configuração

RotaO que faz
GET /webchat/widgetsLista os chats, com o código de instalação de cada um.
POST /webchat/widgetsCria um chat.
GET /webchat/widgets/{id}Consulta um chat.
PUT /webchat/widgets/{id}Altera só os campos enviados.
DELETE /webchat/widgets/{id}Remove o chat. As conversas continuam no CRM.
GET /webchat/widgets/{id}/usageUso do chat.
GET /webchat/widgets/{id}/identity-secretMostra o segredo de identidade.
POST /webchat/widgets/{id}/identity-secretTroca o segredo de identidade.
PUT /webchat/conversations/{entryId}/blockBloqueia ou desbloqueia o visitante de uma conversa.