@lionchat/mcp-server 0.4.10 → 0.5.1

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,40 @@ 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)
+
+WavoipSetting (Ligação WP em caixa QR Code — 1 por inbox, 2026-06-11)
+├── inbox_id (FK) / device_id / device_token (cripto) / status / due_date
+├── record_all_calls (bool) / auto_transcribe (bool) / transcription_provider (groq|openai)
+└── feature flag wavoip_calling; limite de plano wavoip_voice_inboxes; R$70/device/mês
+
+ContactDocument (aba Documentos do contato, 2026-06-11)
+├── 3 fontes agregadas: upload direto + espelho dos cards Kanban + espelho das conversas (só image/file)
+├── dedup por checksum (arquivo repetido conta 1x no storage)
+└── ações: preview, download, renomear, favoritar, excluir (conversas são só-leitura)
 ```
 
 ## Cardinalidades importantes

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

@@ -60,14 +60,23 @@ 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`.
+**Triggers válidos:** `message_received`, `message_sent`, `conversation_created`, `conversation_resolved`, `conversation_reopened`, `label_added`, `label_removed`, `card_created`, `card_moved`, `cron`, `webhook`.
+
+**Trigger `message_sent` (novo 2026-06-11):** par do message_received, mas pra mensagens de SAÍDA — dispara quando atendente, celular (eco do WhatsApp) ou a própria IA/flow envia mensagem (nota privada NÃO dispara). Config: `keywords` (opcional) + `match_type` (`contains`|`exact`). Caso de uso clássico: "quando eu responder do celular, desligar a IA". ATENÇÃO: mensagem da IA também dispara — se a ação for desativar a IA, use keywords que só humanos digitam ou aceite que a primeira resposta da IA aciona o flow. Protegido por anti-loop (profundidade 5) e sessão única por conversa+flow; nunca alimenta `waiting_input`.
 
 **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 +151,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 +174,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 +237,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 +322,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 +398,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 +411,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 +441,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

package/dist/docs/resources/glossary.md

@@ -174,11 +174,21 @@ Glossário completo de termos, status codes, enums e conceitos da plataforma. Us
 
 - `id`: ID interno
 - `name`: nome do agente (ex: "Luna", "Diogo")
+- `paused`: botão de pânico — `true` corta respostas/follow-ups/callbacks na hora (top-level, auditado)
+- `guardrails`: array de limites duros injetados no prompt (ex: anti-pitch)
+- `response_guidelines`: array de diretrizes de estilo de resposta
 - `config.feature_memory`: gera notas no contato ao resolver conversas
 - `config.feature_faq`: gera FAQs sugeridas ao resolver conversas
+- `config.feature_follow_up` + `config.follow_up_steps`: follow-up automático em cadência de até
+  3 etapas (cada ≥5 min, soma ≤24h) quando o cliente some — motor dedicado só-leitura
 - `config.model`: modelo OpenAI usado (gpt-4o, gpt-4o-mini)
 - `config.temperature`: 0.0-1.0
-- `config.instructions`: prompt sistema (Liquid template)
+- `config.instructions`: prompt sistema (Liquid template, até 20.000 chars)
+- `config.activation_label`: etiqueta que ativa o agente na conversa (única por conta)
+- **Cenário (Captain::Scenario)**: instrução situacional inline do assistente; o raciocínio de
+  aplicação fica no "caderninho do cenário" da conversa (scenario_checklist, card Raciocínio)
+- **Regra DITO ≠ SALVO**: a IA só considera coletado o dado que foi PERSISTIDO — salva cada dado
+  na hora e não repergunta o que já salvou
 
 ## Account (Conta)
 
@@ -309,3 +319,39 @@ Glossário completo de termos, status codes, enums e conceitos da plataforma. Us
 Campos MUTÁVEIS (atualizáveis livremente por IA/integração): `marital_status`, `profession` e todos os campos de `address`.
 
 `custom_attribute_definitions` (model=`contact_attribute`) fica reservado a dado de NEGÓCIO genérico que não tem modelo dedicado (ex: "plano contratado", "nicho do cliente").
+
+## Ligações — TRÊS sistemas distintos (não confundir!)
+
+| Sistema | O que é | Tools | Canal |
+|---|---|---|---|
+| **Ligação WP (Wavoip)** | Voz pelo WhatsApp em caixa **QR Code/WAHA** — QR conecta um "device" Wavoip; widget de discagem, gravação e transcrição automática | `wavoip_*` (por inbox: status/token/calls/connect/disconnect/settings) | WhatsApp QR Code |
+| **WhatsApp Calling (Cloud)** | Voz pelo WhatsApp na **API oficial** (enterprise) | `whatsapp_calls_*` + enable/disable_whatsapp_calling | WhatsApp oficial |
+| **VoIP (Zenvia)** | Telefonia COMUM (ramais, saldo, recarga) | `voip_*` | Telefone |
+
+Quando o usuário falar "ligação", descubra o canal: caixa QR Code → Wavoip; caixa oficial →
+whatsapp_calls; telefone fixo/ramal → VoIP Zenvia.
+
+**Wavoip (2026-06-11):** config por inbox (`record_all_calls`, `auto_transcribe`,
+`transcription_provider` groq|openai), feature flag `wavoip_calling`, limite por plano
+`wavoip_voice_inboxes`, R$70/device/mês. Conectar/configurar = admin; discar/histórico = membro
+da caixa. WhatsappCall (Cloud): `status`, `custom_name`, `favorited`, `transcript`/`transcript_status`.
+
+## Chat interno da equipe (InternalChat)
+
+Mensagens ENTRE agentes da conta (não envolve cliente). Salas `direct` (1:1) ou `multi_user`
+(grupo), com reações, fixadas, anexos e não-lidas. Tools `internal_chat_*`. Não confundir com
+nota privada (que mora DENTRO de uma conversa com cliente).
+
+## LionTrack / Jornada do Lead
+
+Rastreamento de navegação do site (tracking_events, pageviews) + painel "Jornada do Lead" em
+Relatórios: mapa visual de por onde os leads andam (nós = páginas, setas = transições), agrupado
+por FASES configuráveis (LiontrackJourneyStage: padrão de URL → fase, match literal).
+Feature flag `liontrack` (404 sem ela). Relatório: `journey_funnel_reports` (v2), janela máx 30
+dias, URLs sem querystring (LGPD).
+
+## Idiomas da plataforma (2026-06)
+
+A plataforma opera com 6 idiomas: `en`, `es`, `fr`, `it`, `pt`, `pt_BR` (default das contas
+brasileiras: pt_BR). Conta com idioma antigo/descontinuado cai em inglês. Notas internas geradas
+pela IA saem no idioma da conta.

package/dist/docs/resources/kanban-deep-dive.md

@@ -253,6 +253,25 @@ Funil "Vendas"
 
 Endpoint: `GET /api/v2/kanban/items/counts` retorna contagem + soma por etapa.
 
+## Controle de acesso por funil (2026-06-10)
+
+Funis agora têm visibilidade por usuário. Um funil é visível pra alguém quando:
+- é admin da conta, OU
+- tem permissão `kanban_view`/`kanban_manage` (custom role), OU
+- o funil está aberto a todos, OU
+- a pessoa participa do funil (está em `settings.agents` ou tem card atribuído)
+
+**Efeitos práticos nas tools:**
+- `funnels_list` retorna SÓ os funis visíveis pro usuário do token
+- `funnels_show` / `stage_stats` de funil não-visível → **404** (não "lista vazia")
+- A resposta dos cards traz selos de permissão calculados no backend:
+  `can_edit`, `can_move`, `can_delete`, `can_assign` (booleans)
+- `kanban_items_move` sem permissão → **403** com mensagem traduzida (antes dava 500/sucesso falso)
+- Cards embutidos na tela da conversa também respeitam a visibilidade
+
+**Pro MCP:** antes de tentar mover/editar card, confira os campos `can_*` do show — se `can_move`
+é false, explique ao usuário que ele não tem acesso àquele funil em vez de tentar mesmo assim.
+
 ## Funil arquivado vs ativo
 
 - `archived = true`: funil escondido da UI principal. Cards ainda existem mas não aparecem nas listas

package/dist/docs/resources/reports-guide.md

@@ -280,6 +280,26 @@ atual. Se since-until = 7d, previous = 7d antes. Pra esses dois, passe `since/un
 inteiro e use o `previous` retornado em vez de comparar na mão.
 Nos demais (agente/time/inbox/label/canal e timeseries) NÃO há `previous` — chame duas vezes.
 
+## Jornada do Lead (LionTrack) — relatório novo (2026-06)
+
+`GET /api/v2/accounts/{id}/journey_funnel_reports` — mapa agregado de navegação dos
+leads no site ANTES de virarem conversa (nós = páginas, arestas = transições página A → página B,
+agrupado por fases configuradas em `liontrack/journey_stages`).
+
+**Filtros (query):** `since`/`until` (janela MÁX 30 dias — acima disso o servidor corta sozinho),
+`utm_source`, `utm_campaign`, `device_name`, `country`, `contact_id` (trilha de 1 lead),
+`with_conversation=true` (só quem virou conversa).
+
+**Retorno:** `nodes` (página, fase, visitas, visitantes únicos), `edges` (transições com contagem),
+totais. URLs vêm SEM querystring (proteção LGPD — e-mail/CPF em URL nunca aparecem).
+
+**Gates:** feature flag `liontrack` (404 se desligada) + permissão de relatórios (admin ou
+report_manage). As fases são geridas pelas tools `liontrack_journey_stages_*` (padrão de URL →
+fase, match literal de substring, sem regex).
+
+**Perguntas que esse relatório responde:** "por onde os leads entram?", "qual página perde mais
+gente?", "quem veio da campanha X navegou por onde antes de chamar?".
+
 ## Quando o usuário pede algo MUITO específico que não existe num endpoint
 
 Se a pergunta requer cálculos custom (ex: "conversas por agente que duraram mais de X minutos"):