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
- O seu site carrega o script
loader.jscom a chave pública do chat. - 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. - A janela abre uma sessão para o visitante e recebe um token de sessão, que vale 30 dias e fica no navegador.
- 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.
| Campo | Regra |
|---|---|
name | Obrigatório, até 80 caracteres. |
allowedOrigins | Obrigató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. |
identityMode | off (padrão), optional ou required. Com optional ou required, o chat ganha um segredo de identidade. |
intakeName, intakeEmail, intakePhone | hidden, optional ou required: o que o formulário inicial pede. |
privacyPolicyUrl | Endereço https. Com ele, o formulário inicial exige o aceite da política. |
defaultCountryCode | DDI usado nos telefones sem DDI, de 1 a 3 dígitos. Padrão 55. |
allowHumanRequest | Mostra a opção de falar com uma pessoa. |
allowAttachments | Deixa o visitante enviar arquivos. |
agentId, workflowId, pipelineId, departmentId | Quem 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:
| Propriedade | Para que serve |
|---|---|
identity | O JWT de identidade do cliente logado. Veja abaixo. |
title | O 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.
identityMode | Sem identity | Com identity válido | Com identity inválido ou vencido |
|---|---|---|---|
off | Visitante anônimo. | O token é ignorado. | O token é ignorado. |
optional | Visitante anônimo. | Cliente identificado. | 401 identity_invalid ou 401 identity_expired. |
required | 403 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:
| Parte | Regra |
|---|---|
| Cabeçalho | alg igual a HS256. |
| Assinatura | HMAC-SHA256 de cabeçalho.conteúdo, com a chave igual ao texto do segredo, exatamente como a API devolve (não decodifique o segredo). |
sub | Obrigatório. O id do cliente no seu sistema, como texto (um número é recusado), até 128 bytes. É o que identifica o cliente entre aparelhos. |
exp | Obrigatório, em segundos Unix. No máximo 24 horas à frente. |
iat, nbf | Opcionais. Não podem estar no futuro. |
name, email, phone | Opcionais. Atualizam os dados do visitante. Um telefone sem DDI recebe o defaultCountryCode do chat; um telefone que não é válido é ignorado. |
| Tamanho | Até 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.
| Rota | O que faz |
|---|---|
POST /public/webchat/{publicKey}/challenge | Devolve um desafio anti-robô (prova de trabalho com SHA-256) que vale 2 minutos e uma única vez. |
POST /public/webchat/{publicKey}/session | Abre 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/intake | Envia 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/messages | Histó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/messages | Envia 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/media | Envia 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/handoff | Pede 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/typing | Avisa aos atendentes que o visitante está digitando (typing). |
GET /public/webchat/session/stream | Eventos 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.
| Evento | Dados |
|---|---|
message | Uma mensagem nova: id, author (visitor, team ou assistant), text, media, options, quote e createdAt. |
typing | A equipe está ou não digitando. |
status | state human (a conversa passou para uma pessoa) ou blocked (o visitante foi bloqueado). |
ping | A 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:
| Status | Código | Quando |
|---|---|---|
400 | challenge_invalid, challenge_expired, challenge_unsolved, challenge_reused | Desafio anti-robô inválido, vencido, errado ou já usado. |
400 | client_message_id_invalid | clientMessageId fora de 8 a 64 caracteres. |
401 | session_invalid, session_expired | Token da sessão ausente, inválido ou vencido. |
401 | identity_invalid, identity_expired | JWT de identidade inválido ou vencido. |
403 | cross_site | Pedido fora da janela do chat. |
403 | origin_not_allowed | O site não está entre os sites permitidos. |
403 | identity_required | O chat só aceita clientes identificados. |
403 | visitor_blocked | O visitante foi bloqueado pela equipe. |
403 | attachments_disabled, human_request_disabled | O chat não aceita anexos ou não oferece atendimento humano. |
404 | widget_not_found, widget_unavailable | Chat inexistente, removido ou pausado. |
409 | intake_pending | Falta responder o formulário inicial. |
413 | attachment_too_large | Arquivo maior que 10 MB. |
415 | attachment_type_refused | Tipo de arquivo não aceito. |
422 | field_required, name_invalid, email_invalid, phone_invalid, consent_required | Respostas do formulário inicial. |
422 | message_empty, message_too_long, option_not_offered | Mensagem vazia, longa demais ou escolha que não foi oferecida. |
429 | rate_limited | Limite de novas sessões por IP e por chat, de mensagens ou de conexões. |
503 | challenge_unavailable | A conferência do desafio está indisponível. Tente de novo em instantes. |
Rotas de configuração
| Rota | O que faz |
|---|---|
GET /webchat/widgets | Lista os chats, com o código de instalação de cada um. |
POST /webchat/widgets | Cria 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}/usage | Uso do chat. |
GET /webchat/widgets/{id}/identity-secret | Mostra o segredo de identidade. |
POST /webchat/widgets/{id}/identity-secret | Troca o segredo de identidade. |
PUT /webchat/conversations/{entryId}/block | Bloqueia ou desbloqueia o visitante de uma conversa. |