Documentação de Integração Webchat v2

Visão geral e fluxo
Instalação rápida (copiar e colar)
Instalação em 1 minuto
Atributos do script
API JavaScript
Configuração no painel
Referência de endpoints
Webhook presence.update
Interações v2.1
Construindo um widget próprio
Limites
Segurança
Retrocompatibilidade com a v1
FAQ e solução de problemas

O webchat conecta um chat no seu site ao sistema de atendimento. O visitante conversa pelo widget; o hub guarda a conversa, repassa cada mensagem ao sistema de atendimento por webhook e entrega as respostas dos atendentes de volta ao widget por polling. A v2 adiciona anexos, recibos de leitura, horário de atendimento, presença (online e digitando) e restauração de histórico.

visitante (widget)  --POST /api/webhooks/webchat/:token-->  hub  --webhook message.received-->  sistema de atendimento
visitante (widget)  <--GET  /api/webchat/messages (polling)--  hub  <--POST /api/messages/sendText|sendMedia--  atendente
visitante (widget)  --POST /api/webchat/presence-->  hub  --webhook presence.update-->  sistema ("digitando...")
atendente abre o ticket  --POST /api/messages/markAsRead-->  hub (status read)  -->  widget mostra "lida" (✓✓)

Convenções desta página: {API} é a URL pública do hub (ex.: https://sua-api.com.br), {token} é o token UUID da conexão webchat e x-api-key é a chave pública do widget (wc_...). O CORS é aberto, então o widget funciona em qualquer domínio.

Informe os dados da sua conexão e todos os exemplos abaixo são preenchidos na hora. Também é possível abrir esta página com ?token=SEU_TOKEN&key=wc_SUA_CHAVE (e &api=https://sua-api.com.br se a API estiver em outro domínio). Nada é enviado para fora do navegador.

APIToken da conexãoChave (x-api-key)

Uma linha no site. Escolha o seu ambiente:

Cada exemplo gera o visitorId (128 bits), envia uma mensagem, faz polling com lastMessageId, since e cursor, e mostra como responder, reagir, editar, apagar e avisar leitura. Contrato completo na seção Interações v2.1.

API="{API}"; TOKEN="{TOKEN}"; KEY="{API_KEY}"
VISITOR="visitor_$(openssl rand -hex 16)"    # 128 bits; guarde por visitante
# 1) enviar mensagem do visitante  -> {"ok":true,"messageId":9012,...}
curl -sS -X POST "$API/api/webhooks/webchat/$TOKEN" \
  -H "x-api-key: $KEY" -H "Content-Type: application/json" \
  -d "{\"visitorId\":\"$VISITOR\",\"visitorName\":\"Ana\",\"message\":\"Olá!\",\"clientMessageId\":\"c_1\"}"
# 2) polling: 1a vez com lastMessageId=0; depois o maior id recebido + since=<cursor>
curl -sS -G "$API/api/webchat/messages/$TOKEN/$VISITOR" \
  --data-urlencode "lastMessageId=0" -H "x-api-key: $KEY"
curl -sS -G "$API/api/webchat/messages/$TOKEN/$VISITOR" \
  --data-urlencode "lastMessageId=9013" --data-urlencode "since=2026-10-17T12:01:03.000Z" \
  -H "x-api-key: $KEY"
# 3) responder (citar) a mensagem 9013
curl -sS -X POST "$API/api/webhooks/webchat/$TOKEN" \
  -H "x-api-key: $KEY" -H "Content-Type: application/json" \
  -d "{\"visitorId\":\"$VISITOR\",\"message\":\"Sim, pode ser.\",\"replyToId\":9013}"
# 4) reagir (emoji vazio remove), editar (15 min), apagar (48 h), avisar leitura
curl -sS -X POST "$API/api/webchat/messages/$TOKEN/$VISITOR/9013/reaction" \
  -H "x-api-key: $KEY" -H "Content-Type: application/json" -d '{"emoji":"👍"}'
curl -sS -X PATCH "$API/api/webchat/messages/$TOKEN/$VISITOR/9012" \
  -H "x-api-key: $KEY" -H "Content-Type: application/json" -d '{"text":"Olá, tudo bem?"}'
curl -sS -X DELETE "$API/api/webchat/messages/$TOKEN/$VISITOR/9012" -H "x-api-key: $KEY"
curl -sS -X POST "$API/api/webchat/read/$TOKEN/$VISITOR" \
  -H "x-api-key: $KEY" -H "Content-Type: application/json" -d '{"lastMessageId":9013}'

// Node 18+ (fetch nativo)
import { randomBytes } from "node:crypto";
const API = "{API}";
const TOKEN = "{TOKEN}";
const KEY = "{API_KEY}";
const visitorId = "visitor_" + randomBytes(16).toString("hex"); // 128 bits; persista por visitante
async function call(method, path, body) {
  const res = await fetch(API + path, {
    method,
    headers: { "x-api-key": KEY, ...(body ? { "Content-Type": "application/json" } : {}) },
    body: body ? JSON.stringify(body) : undefined,
  });
  const data = await res.json().catch(() => null);
  if (!res.ok) throw new Error(res.status + " " + JSON.stringify(data));
  return data;
}
// 1) enviar (replyToId opcional = responder/citar)
async function send(message, replyToId) {
  return call("POST", `/api/webhooks/webchat/${TOKEN}`, {
    visitorId, visitorName: "Ana", message, replyToId,
    clientMessageId: "c_" + Date.now(),
  }); // { ok, messageId, ... }
}
// 2) polling com lastMessageId / since (cursor) / updates
let lastMessageId = 0;
let cursor = "";
async function poll() {
  const qs = new URLSearchParams({ lastMessageId: String(lastMessageId) });
  if (cursor) qs.set("since", cursor);
  const d = await call("GET", `/api/webchat/messages/${TOKEN}/${visitorId}?${qs}`);
  for (const m of d.messages) {
    lastMessageId = Math.max(lastMessageId, m.id);
    console.log("atendente:", m.id, m.text);
  }
  for (const u of d.updates ?? []) console.log("alterada:", u.id, u.deleted ? "(apagada)" : u.text, u.reactions);
  if (d.agentTyping) console.log("atendente digitando...");
  cursor = d.cursor ?? cursor; // o merge das updates deve ser idempotente
  return d;
}
// 3) reagir, editar, apagar, recibo de leitura
const msgPath = (id) => `/api/webchat/messages/${TOKEN}/${visitorId}/${id}`;
const react = (id, emoji) => call("POST", msgPath(id) + "/reaction", { emoji }); // "" remove
const edit = (id, text) => call("PATCH", msgPath(id), { text });
const remove = (id) => call("DELETE", msgPath(id));
const markRead = (lastId) => call("POST", `/api/webchat/read/${TOKEN}/${visitorId}`, { lastMessageId: lastId });
const sent = await send("Olá!");
setInterval(() => poll().catch(console.error), 3000);
// await react(9013, "👍"); await send("Sim!", 9013);

# pip install requests
import secrets
import time
import requests
API = "{API}"
TOKEN = "{TOKEN}"
KEY = "{API_KEY}"
visitor_id = "visitor_" + secrets.token_hex(16)  # 128 bits; persista por visitante
H = {"x-api-key": KEY}
def call(method, path, body=None, params=None):
    r = requests.request(method, API + path, headers=H, json=body, params=params, timeout=20)
    r.raise_for_status()
    return r.json()
def send(message, reply_to_id=None):
    body = {"visitorId": visitor_id, "visitorName": "Ana", "message": message,
            "clientMessageId": f"c_{int(time.time() * 1000)}"}
    if reply_to_id:
        body["replyToId"] = reply_to_id  # responder/citar
    return call("POST", f"/api/webhooks/webchat/{TOKEN}", body)  # {"ok": True, "messageId": ...}
last_message_id = 0
cursor = ""
def poll():
    global last_message_id, cursor
    params = {"lastMessageId": last_message_id}
    if cursor:
        params["since"] = cursor
    d = call("GET", f"/api/webchat/messages/{TOKEN}/{visitor_id}", params=params)
    for m in d["messages"]:
        last_message_id = max(last_message_id, m["id"])
        print("atendente:", m["id"], m["text"])
    for u in d.get("updates", []):
        print("alterada:", u["id"], "(apagada)" if u["deleted"] else u["text"], u["reactions"])
    if d.get("agentTyping"):
        print("atendente digitando...")
    cursor = d.get("cursor") or cursor
def msg_path(mid):
    return f"/api/webchat/messages/{TOKEN}/{visitor_id}/{mid}"
def react(mid, emoji):  # "" remove a reação
    return call("POST", msg_path(mid) + "/reaction", {"emoji": emoji})
def edit(mid, text):  # até 15 min
    return call("PATCH", msg_path(mid), {"text": text})
def remove(mid):  # até 48 h
    return call("DELETE", msg_path(mid))
def mark_read(last_id):
    return call("POST", f"/api/webchat/read/{TOKEN}/{visitor_id}", {"lastMessageId": last_id})
send("Olá!")
while True:
    poll()
    time.sleep(3)

<?php
// PHP 7.4+ com a extensão curl
$API = '{API}';
$TOKEN = '{TOKEN}';
$KEY = '{API_KEY}';
$visitorId = 'visitor_' . bin2hex(random_bytes(16)); // 128 bits; persista por visitante
function hub_call(string $method, string $path, ?array $body = null): array {
    global $API, $KEY;
    $ch = curl_init($API . $path);
    $headers = ['x-api-key: ' . $KEY];
    curl_setopt_array($ch, [
        CURLOPT_CUSTOMREQUEST => $method,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT => 20,
    ]);
    if ($body !== null) {
        $headers[] = 'Content-Type: application/json';
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body, JSON_UNESCAPED_UNICODE));
    }
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    $raw = curl_exec($ch);
    $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    $data = json_decode((string) $raw, true) ?? [];
    if ($status >= 400) {
        throw new RuntimeException("HTTP $status: $raw");
    }
    return $data;
}
// 1) enviar (replyToId opcional = responder/citar)
function hub_send(string $message, ?int $replyToId = null): array {
    global $TOKEN, $visitorId;
    $body = ['visitorId' => $visitorId, 'visitorName' => 'Ana', 'message' => $message,
             'clientMessageId' => 'c_' . round(microtime(true) * 1000)];
    if ($replyToId) { $body['replyToId'] = $replyToId; }
    return hub_call('POST', "/api/webhooks/webchat/$TOKEN", $body); // ['ok' => true, 'messageId' => ...]
}
// 2) polling com lastMessageId / since (cursor) / updates
function hub_poll(int &$lastMessageId, string &$cursor): array {
    global $TOKEN, $visitorId;
    $qs = ['lastMessageId' => $lastMessageId];
    if ($cursor !== '') { $qs['since'] = $cursor; }
    $d = hub_call('GET', "/api/webchat/messages/$TOKEN/$visitorId?" . http_build_query($qs));
    foreach ($d['messages'] ?? [] as $m) {
        $lastMessageId = max($lastMessageId, $m['id']);
        echo "atendente: {$m['id']} {$m['text']}\n";
    }
    foreach ($d['updates'] ?? [] as $u) {
        echo "alterada: {$u['id']} " . ($u['deleted'] ? '(apagada)' : $u['text']) . "\n";
    }
    $cursor = $d['cursor'] ?? $cursor;
    return $d; // $d['agentTyping'] indica atendente digitando
}
// 3) reagir ('' remove), editar (15 min), apagar (48 h), recibo de leitura
function hub_react(int $id, string $emoji): array { global $TOKEN, $visitorId; return hub_call('POST', "/api/webchat/messages/$TOKEN/$visitorId/$id/reaction", ['emoji' => $emoji]); }
function hub_edit(int $id, string $text): array { global $TOKEN, $visitorId; return hub_call('PATCH', "/api/webchat/messages/$TOKEN/$visitorId/$id", ['text' => $text]); }
function hub_delete(int $id): array { global $TOKEN, $visitorId; return hub_call('DELETE', "/api/webchat/messages/$TOKEN/$visitorId/$id"); }
function hub_read(int $lastId): array { global $TOKEN, $visitorId; return hub_call('POST', "/api/webchat/read/$TOKEN/$visitorId", ['lastMessageId' => $lastId]); }
$last = 0; $cursor = '';
hub_send('Olá!');
hub_poll($last, $cursor);

package main
import (
	"bytes"
	"crypto/rand"
	"encoding/hex"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"net/url"
	"strconv"
	"time"
)
const (
	api   = "{API}"
	token = "{TOKEN}"
	key   = "{API_KEY}"
)
var (
	client    = &http.Client{Timeout: 20 * time.Second}
	visitorID = newVisitorID() // 128 bits; persista por visitante
)
func newVisitorID() string {
	b := make([]byte, 16)
	_, _ = rand.Read(b)
	return "visitor_" + hex.EncodeToString(b)
}
func call(method, path string, body any) (map[string]any, error) {
	var rd io.Reader
	if body != nil {
		buf, _ := json.Marshal(body)
		rd = bytes.NewReader(buf)
	}
	req, err := http.NewRequest(method, api+path, rd)
	if err != nil {
		return nil, err
	}
	req.Header.Set("x-api-key", key)
	if body != nil {
		req.Header.Set("Content-Type", "application/json")
	}
	res, err := client.Do(req)
	if err != nil {
		return nil, err
	}
	defer res.Body.Close()
	raw, _ := io.ReadAll(res.Body)
	if res.StatusCode >= 400 {
		return nil, fmt.Errorf("HTTP %d: %s", res.StatusCode, raw)
	}
	var out map[string]any
	_ = json.Unmarshal(raw, &out)
	return out, nil
}
// 1) enviar (replyToId > 0 = responder/citar)
func send(message string, replyToID int) (map[string]any, error) {
	body := map[string]any{
		"visitorId": visitorID, "visitorName": "Ana", "message": message,
		"clientMessageId": "c_" + strconv.FormatInt(time.Now().UnixMilli(), 10),
	}
	if replyToID > 0 {
		body["replyToId"] = replyToID
	}
	return call("POST", "/api/webhooks/webchat/"+token, body)
}
// 2) polling com lastMessageId / since (cursor) / updates
func poll(lastMessageID *int, cursor *string) error {
	q := url.Values{"lastMessageId": {strconv.Itoa(*lastMessageID)}}
	if *cursor != "" {
		q.Set("since", *cursor)
	}
	d, err := call("GET", "/api/webchat/messages/"+token+"/"+visitorID+"?"+q.Encode(), nil)
	if err != nil {
		return err
	}
	if msgs, ok := d["messages"].([]any); ok {
		for _, it := range msgs {
			m := it.(map[string]any)
			if id := int(m["id"].(float64)); id > *lastMessageID {
				*lastMessageID = id
			}
			fmt.Println("atendente:", m["id"], m["text"])
		}
	}
	if ups, ok := d["updates"].([]any); ok {
		for _, it := range ups {
			u := it.(map[string]any)
			fmt.Println("alterada:", u["id"], u["text"], u["deleted"], u["reactions"])
		}
	}
	if t, _ := d["agentTyping"].(bool); t {
		fmt.Println("atendente digitando...")
	}
	if c, ok := d["cursor"].(string); ok && c != "" {
		*cursor = c
	}
	return nil
}
// 3) reagir ("" remove), editar (15 min), apagar (48 h), recibo de leitura
func msgPath(id int) string {
	return "/api/webchat/messages/" + token + "/" + visitorID + "/" + strconv.Itoa(id)
}
func react(id int, emoji string) error {
	_, err := call("POST", msgPath(id)+"/reaction", map[string]any{"emoji": emoji})
	return err
}
func edit(id int, text string) error {
	_, err := call("PATCH", msgPath(id), map[string]any{"text": text})
	return err
}
func remove(id int) error { _, err := call("DELETE", msgPath(id), nil); return err }
func markRead(lastID int) error {
	_, err := call("POST", "/api/webchat/read/"+token+"/"+visitorID, map[string]any{"lastMessageId": lastID})
	return err
}
func main() {
	if _, err := send("Olá!", 0); err != nil {
		panic(err)
	}
	last, cursor := 0, ""
	for {
		if err := poll(&last, &cursor); err != nil {
			fmt.Println("erro:", err)
		}
		time.Sleep(3 * time.Second)
	}
}

Snippet do widget

<script
  src="https://sua-api.com.br/webchat/widget.js"
  data-token="SEU_TOKEN"
  data-api-key="wc_SUA_CHAVE"
  defer></script>

Pronto. O widget busca aparência, horário e limites no hub, então mudanças feitas no painel valem sem editar o site. Um arquivo único, sem dependências e sem build; usa Shadow DOM, então o CSS do seu site não interfere e o do widget não vaza.

Para testar manualmente: /webchat-demo?token=SEU_TOKEN&key=wc_SUA_CHAVE.

Atributo	Padrão	Descrição
`data-token`obrigatório	-	Token UUID da conexão.
`data-api-key`obrigatório	-	Chave pública do widget (`wc_...`).
`data-api-url`	origem do `src`	URL do hub, se o script for servido de outro lugar (CDN, proxy).
`data-position`	painel	`right` ou `left`; sobrepõe o painel.
`data-color`	painel	Cor de destaque em hexadecimal (ex.: `#0F766E`). O contraste do texto é calculado sozinho.
`data-title`	painel	Título do cabeçalho.
`data-collect-whatsapp`	`optional`	`required`, `optional` ou `off`. Quando preenchido, valida 10 a 15 dígitos.
`data-open`	-	`true` abre o chat ao carregar.
`data-lang`	`pt-BR`	`pt-BR`, `en` ou `es`.
`data-footer`	-	`false` oculta o rodapé "Atendimento por ...".

Recursos incluídos: pré-chat (nome, WhatsApp e primeira mensagem), mensagem de boas-vindas, banner offline, status de envio (enviando, enviada, lida), anexos por clipe, arrastar e soltar e colar imagem, miniaturas com lightbox, vídeo, áudio e documentos, formatação *negrito*_itálico_~tachado~`código` e links, badge de não lidas com som discreto, tema escuro automático, tela cheia em telas abaixo de 480px e menu "Encerrar conversa". Nada é renderizado com innerHTML.

Método	Descrição
`HubWebchat.open()`	Abre a janela.
`HubWebchat.close()`	Fecha a janela.
`HubWebchat.toggle()`	Alterna abrir e fechar.
`HubWebchat.identify({ name, whatsapp })`	Pré-preenche o pré-chat (e os dados enviados) com o usuário logado no seu site.
`HubWebchat.on(evento, fn)`	Eventos: `message` (nova resposta do atendente, recebe `{ id, text, mediaUrl, mediaType, fileName, timestamp }`), `open` e `close`.

<button onclick="HubWebchat.open()">Fale conosco</button>
<script>
  window.addEventListener('load', function () {
    HubWebchat.identify({ name: 'Ana Souza', whatsapp: '5511999999999' });
    HubWebchat.on('message', function (m) { console.log('Nova resposta', m.text); });
  });
</script>

Chamadas feitas antes do widget terminar de carregar ficam em fila e são executadas assim que ele estiver pronto. O widget só cria window.HubWebchat no escopo global.

Em Conexões, abra as configurações da conexão webchat. Tudo é salvo por PUT /api/webchat/connections/:token/settings (JWT) e lido pelo widget a cada carregamento.

Grupo	Campos
Aparência	`title`, `color`, `avatarUrl`, `position` (`right`\|`left`), `welcomeMessage`.
Horário de atendimento	`businessHours`: fuso (`timezone`) e faixas `HH:MM` por dia (`mon` a `sun`), início menor que fim, até 4 faixas por dia. `null` remove o horário.
Modo	`availabilityMode`: `auto` segue o horário (sem horário configurado, fica sempre online), `online` força online, `offline` força offline.
Offline	`offlineMessage`: texto exibido no banner quando offline. O visitante ainda pode enviar mensagem; ela fica na fila de atendimento.

curl -X PUT "https://sua-api.com.br/api/webchat/connections/SEU_TOKEN/settings" \
  -H "Authorization: Bearer SEU_JWT" -H "Content-Type: application/json" \
  -d '{
    "title": "Atendimento", "color": "#4F46E5",
    "welcomeMessage": "Olá! Como podemos ajudar?",
    "offlineMessage": "Estamos fora do horário. Deixe sua mensagem.",
    "availabilityMode": "auto",
    "businessHours": {
      "timezone": "America/Sao_Paulo",
      "days": { "mon": [["08:00","18:00"]], "tue": [["08:00","18:00"]], "wed": [["08:00","18:00"]],
                "thu": [["08:00","18:00"]], "fri": [["08:00","18:00"]], "sat": [["09:00","13:00"]], "sun": [] }
    }
  }'

GET /api/webchat/connections/:token/settings (JWT) devolve as configurações atuais, a apiKey, a URL do script e o snippet pronto. Quando offline em modo auto, o widget mostra "Offline · voltamos às HH:MM" no fuso do visitante, usando availability.nextOpenAt.

1. Configuração do widget

GET/api/webchat/widget/:tokensem x-api-key

{
  "success": true,
  "config": {
    "title": "Atendimento", "color": "#4F46E5", "welcomeMessage": "Olá! Como podemos ajudar?",
    "businessName": "Empresa X", "avatarUrl": null, "position": "right",
    "offlineMessage": "Estamos fora do horário...",
    "availability": { "status": "online", "mode": "auto", "timezone": "America/Sao_Paulo", "nextOpenAt": null },
    "upload": { "enabled": true, "maxSizeBytes": 16777216, "accept": ["image/png", "application/pdf", "..."] },
    "polling": { "openIntervalMs": 3000, "idleIntervalMs": 15000 },
    "presence": { "heartbeatIntervalMs": 25000, "typingThrottleMs": 3000 }
  }
}

availability.status: online ou offline; nextOpenAt é ISO 8601 do próximo expediente (ou null).
Use os valores de polling, presence e upload em vez de fixar números no seu código.

2. Upload de anexo

POST/api/webchat/upload/:token

Header x-api-key; corpo multipart/form-data com o campo file (um arquivo).

curl -X POST "https://sua-api.com.br/api/webchat/upload/SEU_TOKEN" \
  -H "x-api-key: wc_SUA_CHAVE" -F "file=@foto.png"

{ "success": true,
  "attachment": { "url": "https://sua-api.com.br/uploads/media/12/webchat/foto-169..-abc.png",
                  "mimeType": "image/png", "mediaType": "image", "fileName": "foto.png", "size": 48213 } }

Status	Código	Significado
400	`MISSING_FILE`	Nenhum arquivo no campo `file`.
401	`INVALID_API_KEY`	Chave inválida.
413	`FILE_TOO_LARGE`	Acima do limite de tamanho.
415	`UNSUPPORTED_MEDIA_TYPE`	Tipo não aceito (SVG e HTML são sempre recusados).
429	`RATE_LIMIT_EXCEEDED`	Muitos uploads.

mediaType: image, video, audio ou document.

3. Mensagem do visitante (texto e/ou anexo)

POST/api/webhooks/webchat/:token

Campo	Tipo	Descrição
`visitorId`	string	Identificador do visitante, `^[A-Za-z0-9_-]{8,128}$`obrigatório
`visitorName`	string	Nome do visitante.
`whatsapp`	string	WhatsApp com DDI e DDD, só dígitos.
`message`	string	Texto ou legenda, até 4096 caracteres. Opcional quando há `attachment`.
`attachment`	object	`{ url, mimeType, fileName, mediaType }`, exatamente como devolvido pelo upload.
`clientMessageId`	string	Id gerado no cliente; é devolvido na resposta para casar a mensagem local.

É obrigatório informar visitorId e (message não vazia ou attachment). A attachment.url precisa ter sido emitida pelo upload desta conexão; qualquer outra URL retorna 400 INVALID_ATTACHMENT.

curl -X POST "https://sua-api.com.br/api/webhooks/webchat/SEU_TOKEN" \
  -H "Content-Type: application/json" -H "x-api-key: wc_SUA_CHAVE" \
  -d '{
    "visitorId": "visitor_3f9c1a7e5b2d4c8091a6e3f7d2b4c5a8",
    "visitorName": "Ana", "whatsapp": "5511999999999",
    "message": "Segue a foto",
    "attachment": { "url": "https://sua-api.com.br/uploads/media/12/webchat/foto-169..-abc.png",
                    "mimeType": "image/png", "fileName": "foto.png", "mediaType": "image" },
    "clientMessageId": "c_lr8x2k_1"
  }'

{ "ok": true, "chatId": 55, "messageId": 9012, "clientMessageId": "c_lr8x2k_1",
  "status": "received", "timestamp": "2026-10-17T12:00:00.000Z" }

Guarde o messageId na mensagem local: é com ele que você casa os recibos de leitura.

4. Polling de respostas

GET/api/webchat/messages/:token/:visitorId?lastMessageId=N

{
  "success": true,
  "messages": [
    { "id": 9013, "direction": "out", "text": "Olá Ana!", "type": "text", "mediaUrl": null, "mediaType": null,
      "mimeType": null, "fileName": null, "timestamp": "2026-10-17T12:00:05.000Z" },
    { "id": 9014, "direction": "out", "text": "segue o boleto", "type": "media",
      "mediaUrl": "https://sua-api.com.br/uploads/media/12/boleto-....pdf", "mediaType": "document",
      "mimeType": "application/pdf", "fileName": "boleto.pdf", "timestamp": "..." }
  ],
  "receipts": { "lastReadMessageId": 9012 },
  "availability": { "status": "online", "mode": "auto", "timezone": "America/Sao_Paulo", "nextOpenAt": null }
}

messages traz só respostas da empresa com id > lastMessageId, em ordem crescente, no máximo 50 por chamada.
mediaType: image, video, audio, document, sticker ou null. type pode ser text, media, interactive ou template; exiba o text.
receipts.lastReadMessageId: toda mensagem do visitante com messageId <= lastReadMessageId está lida (✓✓).
availability acompanha cada resposta, então o status online/offline fica atualizado sem chamada extra.

5. Histórico completo

GET/api/webchat/history/:token/:visitorId?beforeId=N&limit=50

limit de 1 a 100; ordem crescente. Use quando o widget já tem visitorId mas nenhuma mensagem local (outro navegador, storage limpo).

{ "success": true,
  "messages": [ { "id": 9012, "direction": "in", "text": "...", "type": "image", "mediaUrl": "...",
                  "mediaType": "image", "mimeType": "image/png", "fileName": "foto.png",
                  "status": "read", "timestamp": "..." } ],
  "hasMore": false, "receipts": { "lastReadMessageId": 9012 } }

Aqui direction: "in" é a mensagem do visitante e "out" a da empresa.

6. Presença do visitante

POST/api/webchat/presence/:token/:visitorId

curl -X POST "https://sua-api.com.br/api/webchat/presence/SEU_TOKEN/visitor_3f9c..." \
  -H "Content-Type: application/json" -H "x-api-key: wc_SUA_CHAVE" \
  -d '{ "state": "typing" }'

state: online, typing, paused ou offline. Resposta: { "success": true, "availability": { ... } }.

online a cada presence.heartbeatIntervalMs (25 s) enquanto a página estiver visível.
typing ao digitar, no máximo uma vez a cada typingThrottleMs (3 s); paused ao esvaziar o campo ou perder o foco.
offline em pagehide, com fetch(..., { keepalive: true }) (aceita header, ao contrário de sendBeacon).
Erros de presença são silenciosos (best effort). O hub só repassa presença de visitantes que já têm conversa, então só envie depois da primeira mensagem.

7. Marcar como lida (sistema de atendimento)

POST/api/messages/markAsReadtoken da empresa

{ "token": "TOKEN_DA_CONEXAO", "messageId": "wc_... ou id numérico" }

Para webchat, marca essa mensagem do visitante e todas as anteriores da mesma conversa como read. O widget passa a exibir ✓✓ via receipts.lastReadMessageId.

8. Respostas do atendente (sistema de atendimento)

As respostas saem pelos endpoints de envio padrão do hub, usando o visitorId como destinatário (o phoneNumber do chat): POST /api/messages/sendText e POST /api/messages/sendMedia. O hub detecta que a conexão é webchat, não envia via WhatsApp e deixa a mensagem disponível para o polling.

Atenção

Não use o WhatsApp real do visitante como destinatário. Use sempre o visitorId do chat, para não duplicar conversas.

Quem integra o sistema de atendimento recebe, no webhook da conexão, o evento presence.update para exibir "digitando..." e online/offline do visitante:

{
  "event": "presence.update",
  "timestamp": "2026-10-17T12:00:00.000Z",
  "connection": { "id": "<token>", "channel": "webchat", "businessName": "Empresa X" },
  "chat": { "id": 55, "phoneNumber": "visitor_3f9c...", "visitorId": "visitor_3f9c...", "contactName": "Ana" },
  "presence": { "state": "composing", "lastSeenAt": "2026-10-17T12:00:00.000Z" }
}

`presence.state`	Origem (`state` do widget)
`composing`	`typing`
`paused`	`paused`
`available`	`online`
`unavailable`	`offline`

available e unavailable só são enviados quando o estado muda; composing no máximo uma vez a cada 3 s por visitante.
Entrega best effort: 1 tentativa, timeout de 5 s, sem log de entrega e sem reenvio. Não dependa deste evento para lógica crítica.
Responda rápido (HTTP 2xx) e trate o evento de forma idempotente.

Tudo aditivo: widgets v2 que ignoram os campos novos continuam funcionando. Ids são os do servidor (messageId do envio, id do polling e do histórico). Só mensagens que já têm id podem ser citadas, editadas, apagadas ou reagidas.

Formato público da mensagem (polling, histórico e updates)

{
  "id": 9013, "direction": "out", "text": "Olá Ana!", "...": "campos da v2",
  "replyTo": { "id": 9012, "direction": "in", "text": "preview até 140 chars", "mediaType": null, "deleted": false },
  "editedAt": "2026-10-17T12:01:00.000Z",
  "deleted": false,
  "welcome": false,
  "reactions": [ { "by": "agent", "emoji": "👍" }, { "by": "visitor", "emoji": "❤️" } ]
}

replyTo: mensagem citada ou null. Renderize como bloco de citação dentro da bolha; clicar rola até a original, se estiver carregada. direction: "in" é o visitante ("Você"), "out" é o atendente.
editedAt preenchido: mostre "editada".
deleted: true: text, mediaUrl, mimeType, fileName e replyTo vêm null. Mostre "Mensagem apagada" (sem mídia nem ações).
reactions: no máximo uma por lado (agent e visitor); renderize como pílulas sob a bolha.
welcome: true: saudação oficial (veja abaixo).

Polling com alterações, cursor e "digitando"

GET/api/webchat/messages/:token/:visitorId?lastMessageId=N&since=<cursor>

{
  "success": true,
  "messages": [ ... ],
  "updates": [ { "id": 9010, "...": "mensagem completa" } ],
  "cursor": "2026-10-17T12:01:03.000Z",
  "agentTyping": false,
  "receipts": { "lastReadMessageId": 9012 },
  "availability": { ... }
}

messages: respostas novas (id > lastMessageId).
updates: mensagens dos dois lados alteradas depois de since (edição, exclusão, reação, status), máx. 100. Mescle na mensagem local de mesmo id; o merge precisa ser idempotente (o cursor tem 2 s de sobreposição). Sem since (primeiro poll) vem []. Se o id não existe localmente, insira a mensagem em ordem de id (pode ser uma resposta que ainda estava sendo processada, como um anexo lento, quando outra mais nova foi entregue).
cursor: guarde (junto do histórico local) e envie em since no próximo poll. É opaco para o cliente.
agentTyping: true enquanto um atendente digita (expira em 10 s). Mostre uma bolha "digitando..." no fim da lista e esconda quando virar false ou quando chegar mensagem nova. O servidor devolve false quando a mesma resposta traz messages novas.
As respostas entregues em messages passam de sent para delivered e o sistema de atendimento recebe message.status = delivered.

Responder (citar)

No POST /api/webhooks/webchat/:token envie "replyToId": 9013 (id de qualquer mensagem da mesma conversa). Id inexistente ou de outra conversa: 400 INVALID_REPLY_TO. O atendimento recebe message.rawData.context = { "id": "<whatsappMessageId da citada>" }.

Editar, apagar e reagir

Header x-api-key; :messageId é o id do servidor.

Ação	Rota	Corpo	Regras
Editar	`PATCH /api/webchat/messages/:token/:visitorId/:messageId`	`{ "text": "novo" }`	Só do próprio visitante, não apagada, com texto, até 15 min. 1 a 4096 caracteres.
Apagar	`DELETE /api/webchat/messages/:token/:visitorId/:messageId`	-	Só do próprio visitante, até 48 h. Confirme com o usuário antes (sem `window.confirm` em widgets embutidos).
Reagir	`POST /api/webchat/messages/:token/:visitorId/:messageId/reaction`	`{ "emoji": "👍" }`	Qualquer mensagem não apagada. `""` remove. Até 16 caracteres. Tocar na própria reação atual deve removê-la.

Resposta 200: { "success": true, "message": { ...formato público } }; substitua a mensagem local pela devolvida. Erros: 404 MESSAGE_NOT_FOUND, 403 NOT_OWN_MESSAGE, 409 MESSAGE_DELETED, 409 EDIT_WINDOW_EXPIRED, 409 DELETE_WINDOW_EXPIRED, 400 INVALID_TEXT, 400 INVALID_EMOJI. O widget oficial mostra um aviso curto para cada um.

Repasse ao sistema de atendimento: edição chega como message.received com message.type = "edit" (rawData.edit.original_message_id), exclusão como type = "revoke" e reação como event: "message.reaction" (reaction.emoji = null quando removida).

Recibo de leitura para o atendente

POST/api/webchat/read/:token/:visitorId

{ "lastMessageId": 9014 }   // 200: { "success": true, "updated": 2 }

Marca como read as respostas da empresa com id <= lastMessageId (máx. 100 por chamada) e avisa o atendimento (message.status = read). Chame quando o painel estiver aberto, a aba visível (document.visibilityState === "visible") e houver resposta nova renderizada, no máximo uma vez a cada 2 s, também ao abrir o painel e ao voltar para a aba. Erros devem ser silenciosos (best effort).

Saudação (welcomeMessage)

config.welcomeMessage pode ser null/vazio: nesse caso não exiba nenhuma saudação. Quando definida, mostre-a localmente como prévia antes da conversa começar. Ao receber a primeira mensagem do visitante, o hub cria uma mensagem de saída (id menor que a do visitante) com "welcome": true, entregue pelo polling normal (lastMessageId=0) ou pelo histórico. Ao receber uma mensagem com welcome: true, descarte a prévia local para a saudação não aparecer duas vezes, mantendo a ordem do servidor (saudação primeiro). Ao restaurar o histórico com a saudação oficial, não monte a prévia.

Ações do atendente (sistema de atendimento para o hub)

Com o token da empresa; token é o da conexão e to é o visitorId.

Ação	Rota	Corpo
Digitando	`POST /api/messages/sendPresence`	`{ "token", "to", "state": "composing" \| "recording" \| "paused" }` (vale 10 s; reenvie a cada ~5 s)
Editar	`POST /api/messages/edit`	`{ "token", "to", "messageId", "text" }`
Apagar	`POST /api/messages/delete`	`{ "token", "to", "messageId" }`
Reagir	`POST /api/messages/sendReaction`	`{ "token", "to", "reactionMessageId", "reactionEmoji" }` (`""` remove)
Responder	`sendText` / `sendMedia`	`context: { "message_id": "<wid da citada>" }`

Editar e apagar só valem para mensagens da empresa (direction: out). Reação e resposta no webchat não geram mensagem nova: a reação vai para reactions da mensagem alvo e a citação para replyTo.

Se preferir uma interface própria, o ciclo é: gerar visitorId, enviar mensagens, fazer polling, e opcionalmente anexos e presença.

Exemplo com curl

# 1) configuração
curl "https://sua-api.com.br/api/webchat/widget/SEU_TOKEN"
# 2) enviar mensagem
curl -X POST "https://sua-api.com.br/api/webhooks/webchat/SEU_TOKEN" \
  -H "Content-Type: application/json" -H "x-api-key: wc_SUA_CHAVE" \
  -d '{"visitorId":"visitor_3f9c1a7e5b2d4c8091a6e3f7d2b4c5a8","visitorName":"Ana","message":"Olá"}'
# 3) buscar respostas
curl "https://sua-api.com.br/api/webchat/messages/SEU_TOKEN/visitor_3f9c1a7e5b2d4c8091a6e3f7d2b4c5a8?lastMessageId=0" \
  -H "x-api-key: wc_SUA_CHAVE"

Exemplo com JavaScript

const API = 'https://sua-api.com.br';
const TOKEN = 'SEU_TOKEN';
const KEY = 'wc_SUA_CHAVE';
const headers = { 'x-api-key': KEY, 'Content-Type': 'application/json' };
// visitorId com 128 bits, guardado por conexão
function getVisitorId() {
  const k = 'wc_visitor_' + TOKEN;
  let id = localStorage.getItem(k);
  if (!id) {
    const b = crypto.getRandomValues(new Uint8Array(16));
    id = 'visitor_' + Array.from(b, x => x.toString(16).padStart(2, '0')).join('');
    localStorage.setItem(k, id);
  }
  return id;
}
async function sendText(text, name) {
  const res = await fetch(`${API}/api/webhooks/webchat/${TOKEN}`, {
    method: 'POST', headers,
    body: JSON.stringify({ visitorId: getVisitorId(), visitorName: name, message: text,
                           clientMessageId: 'c_' + Date.now() })
  });
  return res.json(); // { ok, messageId, clientMessageId, ... }
}
async function sendFile(file, caption) {
  const fd = new FormData();
  fd.append('file', file);
  const up = await fetch(`${API}/api/webchat/upload/${TOKEN}`, {
    method: 'POST', headers: { 'x-api-key': KEY }, body: fd   // não defina Content-Type
  }).then(r => r.json());
  return fetch(`${API}/api/webhooks/webchat/${TOKEN}`, {
    method: 'POST', headers,
    body: JSON.stringify({ visitorId: getVisitorId(), message: caption || '', attachment: up.attachment })
  }).then(r => r.json());
}
let last = 0;
async function poll() {
  const res = await fetch(`${API}/api/webchat/messages/${TOKEN}/${getVisitorId()}?lastMessageId=${last}`,
                          { headers: { 'x-api-key': KEY } });
  const data = await res.json();
  for (const m of data.messages || []) {
    last = Math.max(last, m.id);
    // renderize com textContent, nunca com innerHTML
  }
  // data.receipts.lastReadMessageId => marque como lidas as suas mensagens com messageId <= esse valor
  setTimeout(poll, 3000);
}
poll();

Boas práticas

Pause o polling com a página oculta (visibilitychange), use backoff exponencial em erro (até 60 s), deduplique mensagens por id, valide tipo e tamanho do arquivo antes do upload e nunca insira texto do servidor com innerHTML.

Item	Limite
Tamanho de anexo	16 MB por padrão (`upload.maxSizeBytes` na configuração)
Tipos aceitos	Lista em `upload.accept`: imagens (JPEG, PNG, GIF, WebP), vídeo (MP4, WebM, QuickTime), áudio (MP3, MP4, OGG, WebM, WAV, AAC, M4A), PDF, Word, Excel, PowerPoint, TXT, CSV e ZIP. SVG e HTML são recusados.
Rate limit de upload	30 uploads a cada 10 minutos por conexão e IP (`429`)
Texto da mensagem	4096 caracteres
Polling	Máx. 50 mensagens por chamada; histórico de 1 a 100 por página
Histórico local do widget	200 mensagens por token

A x-api-key é pública. Ela aparece no HTML do seu site e identifica a conexão, não autentica o visitante. Não reutilize essa chave para nada sensível.
O visitorId é o segredo da conversa. Quem o conhece lê o histórico. Por isso ele deve ter 128 bits de aleatoriedade: visitor_ + 32 hexadecimais de crypto.getRandomValues. Não use Date.now() nem Math.random(), não o exponha em URLs, logs ou analytics.
URL de anexo só do upload. O webhook de mensagem recusa qualquer attachment.url que não tenha sido emitida pelo upload da própria conexão (400 INVALID_ATTACHMENT).
Renderização segura. Texto vindo do servidor ou do visitante deve ser inserido como texto (textContent) e links só com http(s), rel="noopener noreferrer".
Se um visitante suspeitar que o visitorId vazou, "Encerrar conversa" gera um novo e apaga o histórico local.

Nenhum campo ou endpoint da v1 foi removido: o snippet antigo (JavaScript inline) continua funcionando. Os campos novos são opcionais.
visitorId no formato antigo (visitor_<timestamp>_<aleatório>) continua aceito. Widgets novos devem gerar o formato de 128 bits.
O endpoint de mensagem usa /api/webhooks/webchat/:token; a rota antiga /api/webhook/webchat/:token (singular) continua respondendo, mas está deprecated; use o plural.
Para migrar: troque o snippet antigo pelo da seção Instalação. O histórico no servidor é preservado; o visitorId antigo guardado em localStorage (webchat_visitor) não é lido pelo widget novo, que cria uma nova identidade por conexão.
Quem mantém um widget próprio pode adotar a v2 aos poucos: recibos (receipts) e disponibilidade (availability) chegam como campos extras no polling, sem quebrar clientes antigos.

O botão do chat não aparece.

Confira no console do navegador se há o aviso [HubWebchat]. Causas comuns: data-token ou data-api-key ausentes, token incorreto (a rota de configuração responde 404) ou script bloqueado por CSP. Se o seu site usa Content-Security-Policy, libere o domínio do hub em script-src, connect-src (e img-src/media-src para anexos).

Recebo 401 INVALID_API_KEY.

A chave não corresponde ao token informado. Copie novamente o snippet nas configurações da conexão.

O widget aparece como offline, mas era para estar online.

Verifique o modo (availabilityMode) e o fuso (timezone) em businessHours. O modo offline força offline mesmo dentro do horário. Mesmo offline o visitante pode enviar mensagens.

As respostas do atendente não chegam.

Responda usando o visitorId do chat como destinatário. O widget só busca mensagens com polling (a cada 3 s com o chat aberto e 15 s fechado) e pausa quando a aba está oculta; ao voltar para a aba, atualiza na hora.

As mensagens nunca ficam com ✓✓.

A leitura depende do atendente abrir o ticket e o sistema chamar POST /api/messages/markAsRead. O widget só marca como lida a mensagem com messageId menor ou igual a receipts.lastReadMessageId.

O upload falha.

413: arquivo acima do limite; 415: tipo não aceito; 429: aguarde alguns minutos. Se estiver atrás de proxy, confira o limite de corpo (client_max_body_size no nginx) e que o domínio dos anexos é acessível pelo visitante.

O histórico sumiu em outro navegador.

O visitorId fica no localStorage de cada navegador. Outro navegador ou aparelho é outro visitante. Sem storage (modo privado restrito) o widget funciona, mas a conversa não sobrevive ao recarregamento.

Posso ter dois chats na mesma página?

Não. O widget carrega uma única vez por página; um segundo script é ignorado.

Como personalizo o visual?

Cor, título, avatar, posição e mensagens vêm do painel (ou de data-*). O CSS está encapsulado em Shadow DOM, por isso não é sobrescrito por estilos do site.

Webchat v2

Visão geral e fluxo

Instalação rápida (copiar e colar)

A. Widget pronto (embed)

B. Integração direta pela API (widget próprio ou bot)

Instalação em 1 minuto

Crie a conexão

Cole o snippet no seu site