CRM & Chat Operacional (super-chat)

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).

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.