25. CRM & Chat Operacional (super-chat)#
Endpoints que dão suporte ao chat operável do Console (funil, atribuição multi-atendente, notas, busca server-side e respostas rápidas). Todos são tenant-scoped (o company_id vem do JWT/API key autenticado, nunca do corpo) e nunca tocam o WhatsApp — são metadados internos da Catcher.
Respostas rápidas / atalhos — /v1/shortcuts#
Atalhos company-wide expandidos no composer digitando /.
| Método | Rota | Descrição |
|---|---|---|
GET |
/v1/shortcuts |
Lista (ordem: fixados, mais usados, alfabético). |
POST |
/v1/shortcuts |
Cria { trigger, content, pinned? }. trigger normalizado com uma única barra inicial; 409 CONFLICT em duplicado. |
PUT |
/v1/shortcuts/{id} |
Atualiza parcial { trigger?, content?, pinned? }. |
DELETE |
/v1/shortcuts/{id} |
Remove (204). |
POST |
/v1/shortcuts/{id}/use |
Incrementa usage_count (fire-and-forget; alimenta o ranking). 204. |
Funil / kanban — /v1/funnel/stages#
Etapas server-owned: o servidor manda code (estável) e label (humano); o front nunca inventa nome de etapa.
| Método | Rota | Descrição |
|---|---|---|
GET |
/v1/funnel/stages |
Lista { id, code, label, color, position } ordenada por position. |
POST |
/v1/funnel/stages |
Cria { label, code?, color?, position? }. code é slugificado do label quando omitido; 409 em duplicado. |
PATCH |
/v1/funnel/stages/{id} |
Atualiza { label?, color?, position? }. |
DELETE |
/v1/funnel/stages/{id} |
Remove a etapa e desanexa as conversas nela (204). |
PUT |
/v1/instances/{instanceId}/chats/{chatId}/stage |
Atribui a conversa a uma etapa: { stage_code } ("" limpa). 404 em código desconhecido. |
Atribuição multi-atendente (optimistic-lock) — /ownership#
| Método | Rota | Descrição |
|---|---|---|
GET |
/v1/instances/{instanceId}/chats/{chatId}/ownership |
{ owner_user_id, owner_name, version }. Conversa sem dono → version: 0. |
PUT |
/v1/instances/{instanceId}/chats/{chatId}/ownership |
Assume/libera com trava: { expected_version, owner_name?, release? }. owner_user_id vem SEMPRE do JWT (não do corpo). Versão divergente → 409 { current_owner, current_version } (o conflito de handoff humano↔humano / humano↔IA, auditável). |
Busca server-side em 3 fases — /search#
GET /v1/instances/{instanceId}/search?q=<termo> → { data: [{ chat_jid, phone, name, last_snippet, match_reason }] }.
Busca o tenant inteiro (não só a página carregada): (1) contatos por nome + telefone (tokenização digit-aware: um telefone casa o trecho 1900 de R$1.900 mas o preço 19,00 NÃO vira telefone), (2) threads por conteúdo de mensagem, (3) re-rankeada (nome > telefone > mensagem, depois recência). match_reason ∈ {name, phone, message}.
Notas privadas — /notes#
Já documentado em §13.2 (Catcher-exclusive). Cliente novo: crmApi.listNotes/createNote/deleteNote.
Taxonomia de falha de envio#
O error_code estável do envio (ex.: BLOCKED_DUPLICATE_CONTENT, BLOCKED_NO_RECIPROCITY, RECIPIENT_NOT_ON_WHATSAPP, MEDIA_FETCH_FAILED, INSTANCE_NOT_CONNECTED) dirige o card de reenvio do Console: blocks anti-spam oferecem Forçar envio (X-Force-Send: true, auditado); falhas transientes oferecem Reenviar; um número fora do WhatsApp não oferece reenvio.