@lionchat/mcp-server 0.4.9 → 0.5.0

package/dist/client.js

@@ -175,6 +175,11 @@ export class LionChatClient {
         let retries429 = 0;
         let retries5xx = 0;
         let retriesNetwork = 0;
+        // AIDEV-NOTE: B1 — só retentamos 5xx/rede em métodos idempotentes. POST não é
+        // idempotente: reenviar após timeout/502 (quando o Rails JÁ processou) duplicaria
+        // mensagem/contato/conversa. 429 segue retentando p/ todos (é pré-processamento).
+        const httpMethod = (fetchOptions.method || 'GET').toUpperCase();
+        const isIdempotent = ['GET', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS'].includes(httpMethod);
         // AIDEV-NOTE: Max possible attempts = 1 initial + 3 (429) + 1 (5xx) + 1 (network)
         // In practice, only one retry category applies per request
         const maxAttempts = 1 + MAX_RETRIES_429 + MAX_RETRIES_5XX + MAX_RETRIES_NETWORK;
@@ -197,19 +202,21 @@ export class LionChatClient {
                 // once and short-circuit BEFORE parsing so an empty body never throws
                 // "Unexpected end of JSON input". The operation succeeded; return clean success.
                 const rawText = await response.text();
-                if (response.status === 204 || rawText.trim() === '') {
-                    if (response.ok) {
-                        return { success: true, status: response.status };
-                    }
+                const isEmptyBody = response.status === 204 || rawText.trim() === '';
+                if (isEmptyBody && response.ok) {
+                    return { success: true, status: response.status };
                 }
-                // AIDEV-NOTE: Parse response body
+                // AIDEV-NOTE: Parse response body.
+                // B9 — corpo vazio com status de erro: não tenta parsear (JSON.parse('') jogaria
+                // "Unexpected end of JSON input"); deixa responseBody undefined p/ getErrorMessage.
+                // B4 — sempre parseia em try/catch (mesmo com content-type application/json): um
+                // corpo malformado (proxy/CDN/502 parcial) cai no fallback de texto em vez de
+                // jogar SyntaxError cru no LLM.
                 let responseBody;
-                const contentType = response.headers.get('content-type') ?? '';
-                if (contentType.includes('application/json')) {
-                    responseBody = JSON.parse(rawText);
+                if (isEmptyBody) {
+                    responseBody = undefined;
                 }
                 else {
-                    // AIDEV-NOTE: Try parsing as JSON even without content-type header
                     try {
                         responseBody = JSON.parse(rawText);
                     }
@@ -238,8 +245,8 @@ export class LionChatClient {
                     await sleep(delayMs);
                     continue;
                 }
-                // AIDEV-NOTE: 5xx — retry once after 2s
-                if (response.status >= 500 && retries5xx < MAX_RETRIES_5XX) {
+                // AIDEV-NOTE: 5xx — retry once after 2s (apenas métodos idempotentes; ver B1)
+                if (response.status >= 500 && isIdempotent && retries5xx < MAX_RETRIES_5XX) {
                     retries5xx++;
                     await sleep(2000);
                     continue;
@@ -253,8 +260,8 @@ export class LionChatClient {
                 if (err instanceof LionChatApiError) {
                     throw err;
                 }
-                // AIDEV-NOTE: Network/timeout errors — retry once after 2s
-                if (isNetworkError(err) && retriesNetwork < MAX_RETRIES_NETWORK) {
+                // AIDEV-NOTE: Network/timeout errors — retry once after 2s (apenas idempotentes; ver B1)
+                if (isNetworkError(err) && isIdempotent && retriesNetwork < MAX_RETRIES_NETWORK) {
                     retriesNetwork++;
                     lastError = err;
                     await sleep(2000);

package/dist/client.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/docs/instructions.md

@@ -187,6 +187,24 @@ POST /api/v1/accounts/{account_id}/kanban_items
 3. Comparar avg_first_response_time entre agentes
 ```
 
+### Criar campanha de WhatsApp (disparo em massa)
+```
+1. Montar audience: seções Label / Funnel / ConversationAttribute + audience_mode (sum|all)
+2. lionchat_campaigns_estimate_audience (MESMO audience+mode) → mostrar contagem ao usuário
+3. CONFIRMAR com o usuário (é envio em massa — seção 7b)
+4. lionchat_campaigns_create (inbox_id define o tipo: WhatsApp oficial, QR Code/WAHA, SMS, Website)
+5. Acompanhar com lionchat_campaigns_statistics (sent/delivered/read/failed)
+```
+Estrutura do audience: `[{type:'Label', id}, {type:'Funnel', id, stages:[], include_won, include_lost}, {type:'ConversationAttribute', key, value}]`.
+QR Code aceita `template_params` com `delay_min/delay_max/variations` (anti-bloqueio) e `bulk_actions`.
+
+### Criar ferramenta da IA (ai_tool)
+```
+1. lionchat_flow_tools_create (tool_name snake_case + tool_description + flow_data com nó end)
+2. POST /flow_tools/{id}/run pra testar com parâmetros reais
+3. POST /flow_tools/{id}/assistants (assistant_ids) pra vincular ao AI Agente
+```
+
 ### Mudar conta ativa (somente Conector OAuth)
 ```
 1. lionchat_list_my_accounts (ver todas)
@@ -241,12 +259,20 @@ Antes de escolher a ferramenta, cheque se a intenção bate com a coluna da dire
 | Intenção do usuário | Tool certa | Cuidado |
 |---|---|---|
 | Listar / ver não lidas | `lionchat_conversations_list` (`conversation_type: 'unread'`) ou `lionchat_conversations_meta` | NÃO use `lionchat_conversations_unread` — é AÇÃO DE ESCRITA (marca como não-lida) |
-| Buscar por texto (nome, telefone, conteúdo) | `lionchat_conversations_search` / `lionchat_contacts_search` | NÃO baixe tudo com `*_list` e filtre na mão |
+| Buscar por texto (nome, telefone, conteúdo) | `lionchat_conversations_search` / `lionchat_contacts_search` | NÃO baixe tudo com `*_list` e filtre na mão. Busca aceita multi-termo (AND) e dados cadastrais (CPF/CNPJ por dígitos) |
 | Só a contagem / números | `lionchat_conversations_meta` / `lionchat_reports_summary` | Não liste o conteúdo completo |
 | Criar contato | `lionchat_contacts_create` base (path `/contacts`) | NÃO use as variantes `_1` … `_9` |
 | Pausar a IA agora (botão de pânico) | `lionchat_captain_assistants_update` (`paused: true`, top-level) | — |
-| Anexar arquivo a uma mensagem | `lionchat_upload_create` primeiro, depois usar o retorno em `lionchat_conversations_messages_create` | — |
+| Anexar arquivo a uma mensagem | `lionchat_upload_create` primeiro, depois usar o retorno em `lionchat_conversations_messages_create` | Confira `lionchat_upload_limits` se o arquivo for grande |
 | Marcar conversa como **lida** | `lionchat_conversations_update_last_seen` | NÃO use `unread` (esse marca como NÃO-lida) |
+| Criar/gerenciar **campanha** (disparo WhatsApp/SMS) | `lionchat_campaigns_*` (criar, estatísticas) | SEMPRE rode `campaigns_estimate_audience` antes de criar e mostre a contagem. Disparo em massa = confirmação obrigatória (seção 7b) |
+| Criar **flow normal** (responde mensagens na caixa) | `lionchat_flows_create` | Ler design-guide antes (seção 11) |
+| Criar **ferramenta da IA** (flow que o AI Agente invoca) | `lionchat_flow_tools_create` + vincular com `flow_tools` → assistants | NÃO use `flows_create` pra ai_tool. Nó `end` obrigatório. Teste com `flow_tools_run` antes de vincular |
+| Ver **ligações de voz do WhatsApp** (histórico, transcrição) | `lionchat_whatsapp_calls_*` | NÃO confundir com `voip_*` (telefonia Zenvia — ramais/saldo). "Ligação no WhatsApp" = whatsapp_calls |
+| **Jornada do Lead** (por onde o lead navegou no site) | `lionchat_journey_funnel_reports` + fases em `lionchat_liontrack_journey_stages_*` | Janela máx 30 dias; exige feature liontrack |
+| **Exportar contatos** (CSV completo por e-mail) | `lionchat_contacts_export` | Respeita filtros/segmento aplicados |
+| Mensagem pra OUTRO AGENTE (não cliente) | `lionchat_internal_chat_*` (salas e mensagens do time) | NÃO confundir com nota privada (dentro da conversa do cliente) |
+| Achar contato pelo que aconteceu com ele (conversa/card) | `lionchat_contacts_filter` com `linked_records` | Ver api-conventions → registros vinculados |
 
 ## 9. Quando NÃO chamar nenhuma ferramenta
 

package/dist/docs/resources/api-conventions.md

@@ -319,13 +319,60 @@ Quando rate-limited:
 }
 ```
 
-### Search
+### Search (overhaul 2026-06-10)
 
-`GET /search?q=texto` — busca cross-entidade (conversations, contacts, messages)
+`GET /search?q=texto` — busca cross-entidade (conversations, contacts, messages, articles, kanban_items)
 
-`GET /search/contacts?q=texto` — só contatos
+`GET /search/contacts?q=texto` — só contatos (idem `/search/conversations`, `/search/messages`, `/search/articles`, `/search/kanban_items`)
 
-`GET /search/conversations?q=texto` — só conversas
+**Multi-termo com E:** `q` aceita String (espaços = AND implícito) ou Array (`q[]=joao&q[]=silva`),
+cap de 5 termos — cada termo precisa bater (cada um mantém seu OR entre campos).
+
+**Busca cadastral:** CPF/CNPJ/RG/endereço/profissão entram na busca de contatos e conversas, com
+match por dígitos que ignora pontuação (`31.104.475/0001-51` == `31104475000151`; mín 3 dígitos).
+Telefone idem. Cards do Kanban são achados pelo contato/conversa vinculados.
+
+**Filtros estruturados:** params `conversation_filters`, `contact_filters`, `kanban_filters`
+(JSON-string na query) aplicam condições no mesmo formato dos endpoints `/filter` — mesma
+validação (allowlist de chaves, operadores por tipo, cap 10 condições). Payload inválido = 422.
+
+```
+GET /search/conversations?q=pix&conversation_filters=[{"attribute_key":"status","filter_operator":"equal_to","values":["open"]}]
+```
+
+### Filtro de contatos por registros vinculados (2026-06-10)
+
+`POST /contacts/filter` ganhou 3 chaves novas que acham o CONTATO pelo que aconteceu com ele:
+- `conversation_search` — por conversa vinculada (status/etiquetas/caixa)
+- atributos da conversa — condição com `custom_attribute_type: "conversation_attribute"`
+- `kanban_card` — por card vinculado (funil/etapa/prioridade/status)
+Combináveis com E/OU e salváveis como segmento (custom_filters).
+
+### Exportação de contatos (2026-06-10)
+
+`POST /contacts/export` (chega por e-mail) agora sai COMPLETO: cadastral achatado (16 colunas),
+etiquetas, empresa/cidade/país, atributos do contato e da conversa (prefixos contato_/conversa_),
+última conversa (nº/status/caixa/responsável/etiquetas/data) e card Kanban (funil/etapa/prioridade/
+status/valor). Filtros/segmento aplicados valem na exportação. Passar `column_names` explícito
+mantém o comportamento antigo (só as colunas pedidas).
+
+### Limites de upload
+
+`GET /upload_limits` retorna o teto em MB por tipo (`image`, `video`, `audio`, `document`,
+`fallback`). Consulte 1x antes de subir anexo grande — evita 422 no meio do fluxo.
+
+### Webhooks de saída — evento novo (2026-06)
+
+`inbox_updated` entrou na lista de eventos assináveis (`webhooks_create/update`): dispara quando
+uma caixa de entrada é autorizada/reautorizada. Entrega só pra quem assinou o evento.
+
+### Webhook Universal (entrada) — arrays no mapeamento (2026-06)
+
+O `field_mapping` do webhook personalizado aceita caminhos com índice de array:
+`messages.0.content`, `itens.1.sku`. Limites do achatamento: profundidade 5, 10 itens por array,
+500 chaves no total. O mapeamento é POSICIONAL — se a ordem do array variar entre eventos, o
+mesmo caminho captura valores diferentes. Campo `flow_id` na criação liga o webhook a um flow
+(webhook embutido — ver resource de fluxos).
 
 ## Headers úteis pra mandar
 

package/dist/docs/resources/best-practices.md

@@ -122,6 +122,81 @@ Pra reativar: `paused=false`. Toggle é auditado (`audited only: [:paused]`).
 - `config.instructions` (system prompt do agente) aceita até **20.000 caracteres** (antes 10k). Acima de 15k, o frontend mostra aviso "lost in the middle" — prefira colocar instruções críticas no início ou final.
 - **Cache automático** ativo em todos os 15 modelos suportados (GPT-4.1 Nano até GPT-5.2 Pro, o1, o3, o4-mini). Desconto 50-75% no input cachado, sem configuração. Reuso do prompt do agente em múltiplas conversas maximiza a economia.
 
+## Follow-up automático multi-etapa (2026-06)
+
+O follow-up do AI Agente agora suporta **cadência de até 3 etapas** via `config.follow_up_steps`:
+
+```json
+{ "config": { "feature_follow_up": true, "follow_up_steps": [
+  { "after_minutes": 30,  "prompt": "Pergunte gentilmente se ainda tem interesse" },
+  { "after_minutes": 240, "prompt": "Ofereça tirar dúvidas" },
+  { "after_minutes": 1140, "prompt": "Última tentativa, despeça-se cordialmente" }
+] } }
+```
+
+Regras: cada etapa ≥ 5 min; soma total ≤ 1440 min (24h); máx 3 etapas. Campos legados
+`follow_up_time` + `follow_up_prompt` continuam funcionando como 1 etapa única.
+Dispara quando o CLIENTE fica inativo após resposta da IA. O motor de follow-up é dedicado e
+**só-leitura** (não executa ferramentas, não coleta dado — só redige a mensagem de retomada,
+com saída estruturada garantida). `paused=true` no assistente corta os follow-ups também.
+
+## Guardrails e diretrizes de resposta (2026-06)
+
+Dois arrays no assistente (top-level, fora do config):
+- `guardrails`: limites DUROS — o que a IA nunca pode fazer (ex: "Nunca ofereça desconto",
+  proteção anti-pitch: "Não faça discurso de vendas se o cliente só pediu informação").
+- `response_guidelines`: estilo — como responder (ex: "Respostas curtas, sem emojis").
+
+No UPDATE, esses arrays SUBSTITUEM o valor inteiro (não fazem merge) — leia antes, reenvie completo.
+
+## Coleta de dados pela IA — regra DITO ≠ SALVO (2026-06)
+
+Como a coleta de dados/cenários funciona hoje (importante pra diagnosticar "IA repergunta dado"):
+- A IA salva cada dado NA HORA em que o cliente informa (não acumula pro final).
+- O que vale é o que está PERSISTIDO no contato/conversa — "o cliente já disse" não conta
+  enquanto não salvou (DITO ≠ SALVO). Se salvou, ela NÃO repergunta.
+- Campo enviado no lugar errado é redirecionado (ex: CPF mandado como telefone vai pro cadastral).
+- Cadastrais são imutáveis (primeira escrita vale) — ver data-model, seção Contatos.
+- Cenários são instruções inline no prompt (sem troca de personagem); o raciocínio do cenário
+  fica no "caderninho" da conversa (campo scenario_checklist, visível no card Raciocínio).
+- Sem AI Agente ativo na conversa = NENHUMA resposta de IA (motor V1 aposentado em 2026-06).
+
+## Automações: atributo de Conversa vs de Contato (2026-06)
+
+Atributos customizados podem existir com o MESMO nome nos dois escopos (ex: utm_source).
+Nas condições de automação, desambigue com `custom_attribute_type`:
+
+```json
+{ "attribute_key": "utm_source", "custom_attribute_type": "conversation_attribute",
+  "filter_operator": "equal_to", "values": ["google"] }
+```
+
+Sem o tipo, o filtro pode bater no escopo errado. A UI mostra sufixo "(Conversa)/(Contato)".
+
+## Meta Lead e CAPI (2026-06)
+
+- Conexão Meta Lead agora é **por página selecionada** (a BM virou só rótulo — antes puxava todas
+  as páginas da BM). O GET da integração traz `enrichment_active` e `pending_businesses` (BMs com
+  pendência de permissão).
+- Meta CAPI: o evento `InitiateCheckout` foi RENOMEADO para `begin_checkout`.
+
+## Campanhas: audiência acumulativa (2026-06)
+
+`audience` aceita 3 tipos de seção combináveis: `Label`, `Funnel` (com stages/include_won/include_lost)
+e `ConversationAttribute` ({key, value}). O campo `audience_mode` define a combinação ENTRE seções:
+- `"sum"` (default): união — contato em QUALQUER seção entra
+- `"all"`: interseção — contato precisa atender TODAS as seções preenchidas
+
+SEMPRE rode `campaigns_estimate_audience` com o MESMO audience+audience_mode antes de criar a
+campanha e mostre a contagem ao usuário — estimativa e disparo usam o mesmo motor (não divergem).
+
+## Agendamento (booking): idempotência e limites (2026-06)
+
+- Reservar o MESMO contato+evento+horário de novo retorna a reserva existente (não duplica) —
+  retry de rede é seguro.
+- Rate limit da reserva pública: 10/5min por IP + 20/min por conta (429 ao estourar).
+- Todo agendamento aparece vinculado a uma conversa (cria/reusa a conversa do contato).
+
 ## Variáveis de conta (account_variables)
 
 Pra dados que se repetem (slogans, endereços, horários):

package/dist/docs/resources/conversation-flows.md

@@ -291,6 +291,26 @@ Endpoint: `POST /api/v1/accounts/{account_id}/conversations/{conversation_id}/sc
 | `recurrence_count` | não | Quantas vezes repetir |
 | `template_params` | não | Parâmetros de template WhatsApp |
 
+## Flows e cadeias de automação
+
+### Disparo de flow por webhook (Webhook Universal embutido, 2026-06)
+
+Além dos triggers de evento (mensagem recebida, conversa criada, etiqueta, card, cron), um flow
+pode ser disparado por **webhook externo próprio**: cria-se a integração embutida via
+`POST /custom_webhook_integrations` com `flow_id`, e o node `start` ganha um item
+`webhook_received` com o `integration_id`. O sistema gera URL única; qualquer evento postado nela
+resolve contato/conversa (mesmas regras do Webhook Universal) e dispara o flow.
+Receita completa no resource **FlowBuilder — Guia de Design** (seção do trigger `webhook`).
+
+### Proteção anti-loop entre motores (2026-06)
+
+Automações e flows podem se encadear (automação dispara flow, flow dispara automação...).
+Cada hand-off entre motores incrementa uma profundidade interna; no **5º hand-off** a cadeia é
+cortada silenciosamente (`MAX_CHAIN_DEPTH = 5`). Sintoma: "o flow X não disparou" no fim de uma
+cadeia longa. É proteção contra loop infinito — redesenhe a cadeia pra ficar mais curta em vez
+de contornar. Além disso, a IA que trava no anti-loop **avisa um humano** (notificação) em vez de
+ficar muda (2026-06-05).
+
 ## Eventos importantes (pra automation)
 
 | Evento | Quando dispara |

package/dist/docs/resources/data-model.md

@@ -149,6 +149,13 @@ Company
 - `additional_attributes` (jsonb): campos do sistema porém **EDITÁVEIS via API** (`permitted_params` permite `additional_attributes: {}`). Guarda chaves padrão como `city`, `company`, `country_code` — que são as chaves filtráveis em `lib/filters/filter_keys.yml` (tipo `additional_attributes`). NÃO é não-editável.
 - `custom_attributes` (jsonb): dado de negócio livre, definido pelo cliente via Atributos Customizados.
 
+**Dados cadastrais (`additional_attributes.cadastral`):** CPF, CNPJ, RG, passaporte, nascimento,
+gênero, estado civil, profissão e endereço completo moram em `additional_attributes->cadastral`.
+São **IMUTÁVEIS por padrão** (primeira escrita vale) — alterar exige `force_update: true`, que SÓ
+o painel humano usa. IA e integrações NUNCA passam force_update. Endpoint dedicado:
+`PATCH /contacts/{id}/cadastral` (tool `contacts_update_cadastral`). NÃO grave cadastral como
+custom_attribute. Regra absoluta relacionada: NUNCA sobrescrever `phone_number` já preenchido.
+
 **Padrões de `source_id` por canal:**
 - Waha: `5511999999999@c.us` (1-on-1) ou `120363xxx@g.us` (grupo) ou `XXXX@lid` (LID)
 - WhatsApp Cloud: `5511999999999` (E.164 sem prefixo)
@@ -221,11 +228,33 @@ Captain::Assistant
 ├── name
 ├── description
 ├── paused (boolean, default false) — botao de panico (2026-05-22). true = pausa respostas, follow-up e callbacks. Auditado. Top-level, NAO mora em config.
-├── config (jsonb: model, temperature, instructions, feature_memory, feature_faq, ...)
-├── guardrails (string[])
-├── response_guidelines (string[])
+├── config (jsonb) — chaves principais:
+│     model, temperature, instructions (max 20.000 chars), feature_memory, feature_faq,
+│     feature_follow_up (bool), follow_up_steps (array de {after_minutes, prompt} — ATE 3 etapas,
+│       cada uma >= 5 min, soma <= 1440 min/24h; legado follow_up_time+follow_up_prompt = 1 etapa),
+│     activation_label (etiqueta que ativa o agente — unica por conta),
+│     min_response_time / max_response_time (delay humanizado, 1-60s),
+│     disabled_tools (array de IDs de tools desativadas pro assistente),
+│     offer_ids / media_asset_ids / booking_event_type_ids (arrays de IDs vinculados),
+│     products (array legado de produtos)
+├── guardrails (jsonb array de strings — limites duros injetados no prompt, ex: anti-pitch)
+├── response_guidelines (jsonb array de strings — diretrizes de estilo de resposta)
 └── active_conversations_count
 
+⚠️ UPDATE de assistant: `config` faz MERGE PARCIAL (chaves não enviadas são preservadas);
+`guardrails`/`response_guidelines` SUBSTITUEM o array inteiro.
+
+Captain::Scenario (cenários do assistente — instruções inline, sem handoff)
+├── assistant_id (FK)
+├── title / description
+├── instruction (text — tools referenciadas como links markdown [Titulo](tool://id))
+├── tools (jsonb — auto-extraído da instruction)
+├── enabled (bool)
+└── trigger_type (llm_interpreted [default] | on_assistant_activation | on_first_customer_message)
+      ⚠️ trigger_type NAO é editável via API hoje — todo cenário criado por API fica em
+      llm_interpreted (a IA decide aplicar lendo a conversa). Os modos programáticos só
+      via banco/console por enquanto.
+
 Captain::AssistantResponse (FAQ)
 ├── assistant_id (FK)
 ├── question
@@ -360,9 +389,30 @@ MetaLeadIntegration (Facebook Lead Ads)
 ├── account_id (FK)
 ├── page_id
 ├── page_name
+├── business_id / business_name (BM dona da página — rótulo, desde 2026-06 a conexão é POR PÁGINA)
 ├── facebook_page_id (FK polimórfico)
 ├── status (active/token_expired/paused)
 └── meta_lead_forms (has_many)
+
+CustomWebhookIntegration (Webhook Universal — entrada)
+├── account_id (FK)
+├── name / token (URL única) / active
+├── field_mapping (jsonb — suporta caminhos com índice de array: messages.0.content)
+├── event_automation_mapping (jsonb)
+└── flow_id (FK opcional → Flow; presente = webhook EMBUTIDO de flow, oculto da listagem standalone)
+
+LiontrackJourneyStage (regras de fase da Jornada do Lead — feature flag liontrack)
+├── account_id (FK)
+├── stage (nome da fase, ex: Topo/Meio/Fundo/Compra)
+├── url_pattern (match literal de substring, <= 255 chars — SEM regex)
+└── position (int, ordem)
+
+WhatsappCall (Ligação WhatsApp — enterprise, voz via Cloud API)
+├── account_id / conversation_id / contact_id (FKs)
+├── status (ringing/accepted/completed/failed) / direction
+├── duration_seconds / accepted_by_agent_id
+├── custom_name (observação) / favorited (bool)
+└── transcript / transcript_status (pending/processing/completed/failed — IA da conta)
 ```
 
 ## Cardinalidades importantes

package/dist/docs/resources/flowbuilder-design-guide.md

@@ -63,11 +63,18 @@ Todo node tem essa estrutura base:
 **Triggers válidos:** `message_received`, `conversation_created`, `conversation_resolved`, `conversation_reopened`, `label_added`, `label_removed`, `card_created`, `card_moved`, `cron`, `webhook`.
 
 **Campos de filtro por trigger (IMPORTANTE — nomes exatos):**
-- `message_received`: `keywords` (array) + `match_type` (`'exact'` ou `'contains'`, default `contains`). NÃO use `match_mode` aqui.
+- `message_received`: `keywords` (array, obrigatório, cada termo com mín 3 chars) + `match_type` (`'exact'` ou `'contains'`, default `contains`). NÃO use `match_mode` aqui. Dispara em QUALQUER mensagem do cliente que case (não só na primeira) — só mensagem de cliente dispara, nunca de agente.
 - `conversation_created` / `conversation_reopened`: filtro opcional de keywords via `match_mode` (`'any'`, `'contains'`, `'exact'`, `'customer_initiated'`, `'agent_initiated'`) + `keywords`. Só ESTES dois triggers usam `match_mode`.
 - `label_added` / `label_removed`: `label_names` (array de slugs). NÃO use `label` (singular) — é ignorado.
 - `card_created` / `card_moved`: `funnel_ids` (array) + `funnel_stages` (array de `"funnel_id:stage"`).
 
+**Trigger `webhook` — Webhook Universal EMBUTIDO (novo 2026-06):** o flow pode ser disparado por um webhook próprio, criado automaticamente. Receita via API:
+1. Criar o flow normalmente (`flows_create`).
+2. `POST /custom_webhook_integrations` com `{ "custom_webhook_integration": { "flow_id": <id do flow> } }` — o sistema cria a integração embutida (idempotente: repetir retorna a mesma; nome automático "Flow: <nome>"; auto-mapeia todos os eventos → este flow) e retorna a URL única do webhook.
+3. No node `start`, adicionar item `{ "type": "webhook_received", "config": { "integration_id": <id da integração> } }`.
+4. Salvar o flow (`flows_update`) — o save sincroniza a ativação do webhook embutido (remover o item desativa a integração automaticamente).
+Webhooks embutidos NÃO aparecem na listagem de integrações standalone; excluir o flow destrói o webhook; duplicar o flow NÃO copia o gatilho embutido. Rate limit do endpoint público: 60/min por token.
+
 **Handles que SAEM:** `success`.
 
 ### 2.2 `send_message`
@@ -142,6 +149,8 @@ Todo node tem essa estrutura base:
 - `validation: 'options'` → `option_<valor>` para cada valor em `acceptedOptions` (ex: `option_1`, `option_2`, `option_sim`) + `timeout`
 - `validation: 'regex'` → `success`, `timeout`
 
+**Timeout AGORA dispara de verdade (corrigido 2026-06-09):** `waitTime` + `waitUnit` agendam o estouro — se o cliente não responder no prazo, o flow segue pelo handle `timeout`. Antes dessa data o backend ignorava o waitTime (flows antigos que dependiam do timeout passaram a funcionar). Sempre ligue um edge no handle `timeout` quando definir waitTime; sem edge, o flow simplesmente para ali no estouro.
+
 **REGRA:** depois de wait_response com options, NUNCA coloque node `condition` pra ramificar — ligue os edges direto nos handles `option_X`.
 
 ### 2.4 `condition`
@@ -163,6 +172,8 @@ Todo node tem essa estrutura base:
 
 **ATENÇÃO — atributo customizado é SINGULAR:** `contact.custom_attribute.X` e `conversation.custom_attribute.X` (também `account.custom_attribute.X`). Usar plural `custom_attributes` resolve VAZIO — vale tanto no `field` da condição quanto em mensagens/variáveis `{{...}}`.
 
+**Dados cadastrais — forma curta é a canônica (2026-06):** `{{contact.cpf}}`, `{{contact.cnpj}}`, `{{contact.rg}}`, `{{contact.address.number}}`, `{{contact.address.street}}` etc. O backend traduz internamente pra `contact.cadastral.*` (flows antigos com a forma longa continuam resolvendo). NÃO use `contact.attributes.cpf` nem `contact.custom_attribute.cpf` — cadastral NÃO é custom attribute.
+
 **Operadores válidos (lista real do runtime):**
 
 | Operador | Uso |
@@ -224,11 +235,13 @@ Use operador numérico (`greater_than`, `less_than`, `number_range`) SÓ em atri
 | `assign_team` | `{ team_id }` | Atribui time |
 | `change_status` | `{ status: 'open' \| 'resolved' \| 'pending' \| 'snoozed' }` | Muda status da conversa |
 | `change_priority` | `{ priority: 'urgent' \| 'high' \| 'medium' \| 'low' }` | Muda prioridade |
-| `add_label` | `{ labels: ['slug1', 'slug2'] }` | Adiciona labels |
-| `remove_label` | `{ labels: ['slug'] }` | Remove labels |
+| `add_label` | `{ labels: ['slug1', 'slug2'] }` | Adiciona labels ao CONTATO |
+| `remove_label` | `{ labels: ['slug'] }` | Remove labels do CONTATO |
+| `add_conversation_label` | `{ labels: ['slug'] }` | Adiciona labels à CONVERSA (não ao contato) |
+| `remove_conversation_label` | `{ labels: ['slug'] }` | Remove labels da CONVERSA |
 | `mute_conversation` | `{}` | Silencia notificações |
 | `add_private_note` | `{ content: 'texto' }` | Adiciona nota interna |
-| `create_kanban_item` | `{ funnel_id, funnel_stage, item_details? }` | Cria card no Kanban |
+| `create_kanban_item` | `{ funnel_id, funnel_stage, title?, description? }` | Cria card no Kanban — `funnel_id` e `funnel_stage` OBRIGATÓRIOS; `title`/`description` aceitam variáveis `{{ }}` |
 | `move_kanban_item_to_stage` | `{ funnel_stage }` | Move card (precisa ter card vinculado) |
 | `move_kanban_stage` | `{ funnel_id, funnel_stage }` | Idem |
 | `set_kanban_item_status` | `{ status: 'won' \| 'lost' \| 'active' }` | Marca status do card |
@@ -307,6 +320,8 @@ Lembre: o atributo lido é SINGULAR (`custom_attribute`).
 
 **`aiMode` válidos:** `generate`, `intent`, `sentiment`, `extract`.
 
+**Contexto da conversa:** campo `contextMessages` define quantas mensagens recentes a IA enxerga — valores válidos `25`, `50`, `75`, `100` (ampliado em 2026-06; antes o teto era ~20). Os modos `intent`/`sentiment`/`extract` rodam no motor contido (texto puro, sem persona nem ferramentas — mais barato e sem risco de vazamento); `generate` usa o assistente Captain.
+
 **Intent — campo EXATO:** `aiIntents` é um ARRAY DE OBJETOS `{ "name": "..." }`. NÃO use `aiIntentOptions` (array de strings) — é ignorado. A intenção classificada também fica disponível na variável de sessão **`ai_intent`** (use como `{{ai_intent}}` adiante).
 
 **Handles que SAEM dependem do mode:**
@@ -381,7 +396,7 @@ Atualiza nome/descrição/foto de grupo WhatsApp. Use só quando flow roda em in
 
 **Handles que SAEM:** `success`, `error`.
 
-### 2.12 `activate_flow`
+### 2.12 `activate_flow` (LEGADO — prefira action `start_flow`)
 
 ```json
 {
@@ -394,6 +409,8 @@ Atualiza nome/descrição/foto de grupo WhatsApp. Use só quando flow roda em in
 
 **Handles que SAEM:** `success`, `error`.
 
+**ATENÇÃO:** este node saiu do menu do editor (legado) — o motor ainda executa flows antigos que o usam, mas em flows NOVOS use `action` com `key: 'start_flow'` e `config: { flow_id }`. Não crie nodes `activate_flow` novos.
+
 ### 2.13 `end` (encerra ramo / define retorno do ai_tool)
 
 Node terminal, sem handles de saída. Em flow `conversation` apenas encerra aquele ramo. Em flow `ai_tool` é OBRIGATÓRIO: o `data` do `end` define o que volta pro LLM (modo de saída + template do resultado).
@@ -422,10 +439,22 @@ O campo `flow_type` (definido na criação, IMUTÁVEL depois) decide a natureza
 | Inboxes | usa `inbox_ids` | **PROIBIDO** ter inboxes (validação barra) |
 | Campos extra | — | `tool_name` (snake_case, `[a-z][a-z0-9_]`, max 50) + `tool_description` (max 500) OBRIGATÓRIOS |
 | Retorno | manda mensagens | retorna dado estruturado ao LLM via node `end` |
-| Nodes permitidos | todos | SÓ: `start`, `end`, `api`, `condition`, `set_variable`, `ai`, `note` |
+| Nodes permitidos | todos | `start`, `end`, `api`, `condition`, `set_variable`, `ai`, `note`, `randomizer`, `action`, `send_message` |
 
 Se o cliente pediu "uma ferramenta que a IA usa pra consultar X / calcular Y", é `ai_tool`. Se pediu "quando chega mensagem, faça Z", é `conversation`. Na dúvida, `conversation`.
 
+**No flow `ai_tool`, o node `action` NÃO aceita as keys da aba "Sistema"** (`send_webhook` /
+`start_flow`) — elas só valem em flow `conversation`. No `action` de um `ai_tool` use apenas keys
+das abas Conversas / Contatos / Kanban (ex: `add_label`, `change_status`, `update_attribute`,
+`create_kanban_item`). Para gravar atributo no `ai_tool`, use `action` com `update_attribute`
+(o antigo node `save_attribute` foi removido — não existe mais em nenhum tipo de flow).
+
+**Proteção anti-loop por profundidade (2026-06):** quando um flow dispara automação que dispara
+outro flow (cadeia entre motores), cada hand-off incrementa um contador interno (`_activation_depth`).
+No 5º hand-off (`MAX_CHAIN_DEPTH = 5`) a cadeia é cortada silenciosamente. Se um flow "não disparou"
+no fim de uma cadeia automação→flow→automação, suspeite desse limite — é proteção, não bug.
+Não tente contornar criando flows intermediários.
+
 ---
 
 ## 3. Edges

package/dist/docs/resources/flowbuilder-patterns.md

@@ -351,6 +351,88 @@
 
 ---
 
+## 11. Flow disparado por webhook externo (Webhook Universal embutido)
+
+**Caso:** sistema externo (checkout, formulário, ERP) chama uma URL e o flow roda na conversa do contato — etiqueta + mensagem.
+
+**Passo a passo via API (a ordem importa):**
+1. `flows_create` com o flow_data abaixo (sem o item webhook ainda)
+2. `POST /custom_webhook_integrations` com `{ "custom_webhook_integration": { "flow_id": <id> } }` → guarde `id` (integration_id) e a URL retornada
+3. `flows_update` adicionando o item `webhook_received` no start com o `integration_id`
+
+```json
+{
+  "nodes": [
+    { "id": "n1", "type": "start", "position": { "x": 50, "y": 300 }, "data": { "label": "Início", "items": [
+      { "type": "webhook_received", "config": { "integration_id": 123 } }
+    ] } },
+    { "id": "n2", "type": "action", "position": { "x": 370, "y": 300 }, "data": { "label": "Marca origem", "items": [
+      { "key": "add_conversation_label", "config": { "labels": ["compra-confirmada"] } }
+    ] } },
+    { "id": "n3", "type": "send_message", "position": { "x": 690, "y": 300 }, "data": { "label": "Confirma", "messageItems": [
+      { "id": "m1", "type": "text", "content": "{{contact.name}}, recebemos a confirmação do seu pedido! 🎉" }
+    ] } }
+  ],
+  "edges": [
+    { "id": "e1", "source": "n1", "target": "n2", "sourceHandle": "success", "type": "deletable", "animated": true },
+    { "id": "e2", "source": "n2", "target": "n3", "sourceHandle": "success", "type": "deletable", "animated": true }
+  ]
+}
+```
+
+---
+
+## 12. Ferramenta da IA (ai_tool) mínima — consulta API + retorno estruturado
+
+**Caso:** a IA precisa consultar um sistema externo durante a conversa (ex: status do pedido). Criar via `flow_tools_create` (NÃO `flows_create`), depois vincular ao assistente com `POST /flow_tools/{id}/assistants`.
+
+```json
+{
+  "tool_name": "consultar_pedido",
+  "tool_description": "Consulta o status do pedido do cliente pelo número. Use quando o cliente perguntar do pedido dele.",
+  "flow_data": {
+    "nodes": [
+      { "id": "n1", "type": "start", "position": { "x": 50, "y": 300 }, "data": { "label": "Início" } },
+      { "id": "n2", "type": "api", "position": { "x": 370, "y": 300 }, "data": { "label": "Consulta ERP", "method": "GET", "url": "https://erp.exemplo.com/pedidos/{{numero_pedido}}", "headers": [{ "key": "Authorization", "value": "Bearer {{env.ERP_TOKEN}}" }], "apiResponseVar": "pedido" } },
+      { "id": "n3", "type": "end", "position": { "x": 690, "y": 300 }, "data": { "label": "Retorno", "mode": "structured" } },
+      { "id": "n4", "type": "end", "position": { "x": 690, "y": 480 }, "data": { "label": "Erro", "mode": "structured" } }
+    ],
+    "edges": [
+      { "id": "e1", "source": "n1", "target": "n2", "sourceHandle": "success", "type": "deletable", "animated": true },
+      { "id": "e2", "source": "n2", "target": "n3", "sourceHandle": "success", "type": "deletable", "animated": true },
+      { "id": "e3", "source": "n2", "target": "n4", "sourceHandle": "error", "type": "deletable", "animated": true }
+    ]
+  }
+}
+```
+
+**Lembretes ai_tool:** nó `end` é OBRIGATÓRIO; sem `inbox_ids`; nodes permitidos = `start`, `end`, `api`, `condition`, `set_variable`, `ai`, `randomizer`, `action`, `send_message`, `note` (sem `wait`/`wait_response`/`update_group`); `action` sem keys da aba Sistema (`send_webhook`/`start_flow`). Teste com `POST /flow_tools/{id}/run` antes de vincular ao assistente.
+
+---
+
+## 13. Etiqueta na CONVERSA vs no CONTATO
+
+**Caso:** marcar a conversa atual sem "sujar" o cadastro do contato (ex: assunto desta conversa), ou o inverso (perfil permanente do contato).
+
+```json
+{
+  "nodes": [
+    { "id": "n1", "type": "start", "position": { "x": 50, "y": 300 }, "data": { "label": "Início", "triggers": [{ "type": "message_received", "keywords": ["orçamento"], "match_type": "contains" }] } },
+    { "id": "n2", "type": "action", "position": { "x": 370, "y": 300 }, "data": { "label": "Marca", "items": [
+      { "key": "add_conversation_label", "config": { "labels": ["pediu-orcamento"] } },
+      { "key": "add_label", "config": { "labels": ["interessado-em-comprar"] } }
+    ] } }
+  ],
+  "edges": [
+    { "id": "e1", "source": "n1", "target": "n2", "sourceHandle": "success", "type": "deletable", "animated": true }
+  ]
+}
+```
+
+**Regra de bolso:** fato sobre ESTA conversa → `add_conversation_label` / `remove_conversation_label`. Característica permanente do CONTATO → `add_label` / `remove_label`.
+
+---
+
 ## Como usar este catálogo
 
 1. **Identifique o pattern mais próximo** do que o cliente pediu