@lionchat/mcp-server 1.12.0 → 1.13.0

package/dist/docs/instructions.md

@@ -18,7 +18,9 @@ Comprovado em produção (24/07): a sessão que dizia "não há função de list
 - **Famílias principais pra pesquisar:** conversations, conversations_messages, contacts,
   kanban_items, funnels, flows, flow_tools, campaigns, macros, automation_rules, agents, teams,
   inboxes, labels, canned_responses, reports, sla, csat, captain_assistants, captain_documents,
-  scheduled_messages, custom_attributes, webhooks, eclinica_integrations, tasks, notifications.
+  scheduled_messages, custom_attributes, webhooks, eclinica_integrations, tasks, notifications,
+  lead_forms (Formulários públicos de captação), guru_subscription (gestão da assinatura da PRÓPRIA
+  conta no LionChat — feature liberada conta a conta).
 - Só depois de pesquisar e não encontrar é que se pode dizer que a função não existe.
 - **Trabalho volumoso** (relatório de muitas conversas/cards): as listas são paginadas (25-100 por
   página) — faça em ETAPAS ao longo de várias respostas, acumulando os resultados; nunca desista
@@ -47,6 +49,8 @@ Account (conta/empresa)
  ├─ Captain::Assistant (AI Agente / IA de atendimento)
  │   └─ Captain::Scenario (instrução situacional; pode FIXAR parâmetro de tool em tool_bindings)
  ├─ AccountTask (agenda/tarefas)
+ ├─ LeadForm (formulário público de captação)
+ │   └─ LeadFormResponse (preenchimento: in_progress / completed / abandoned)
  └─ Booking (agendamento de demonstração/reunião)
 ```
 
@@ -360,6 +364,7 @@ Antes de escolher a ferramenta, cheque se a intenção bate com a coluna da dire
 | 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) | — |
+| Criar/editar **formulário público de captação** (página de captura própria) | `lionchat_lead_forms_create` / `_update` | Leia `lionchat://docs/formularios-publicos` ANTES — o desenho vai em `form_data` e só entra no ar depois do `publish` (que valida o desenho e pode voltar 422 com a lista de pendências). Escrita é só de administrador |
 | 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) |

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

@@ -442,6 +442,13 @@ mantém o comportamento antigo (só as colunas pedidas).
 `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.
 
+**Desde 15/08/2026 o TIPO não rejeita mais anexo de mensagem** — a validação passou a ser só de
+tamanho. Tipo sem balde próprio (nem imagem, nem vídeo, nem áudio) cai no balde de **documento**,
+que é o maior. Ou seja: `upload_limits` continua sendo a única fonte dos tetos, mas a resposta
+"esse formato não é aceito" deixou de existir nesse caminho. Os caminhos que **continuam** com
+lista fechada de tipos são o upload por URL (`/upload` com `#validate`, usado no teste de mídia do
+FlowBuilder) e o chat interno da equipe.
+
 ### Webhooks de saída — evento novo (2026-06)
 
 `inbox_updated` entrou na lista de eventos assináveis (`webhooks_create/update`): dispara quando

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

@@ -330,7 +330,7 @@ Como a coleta de dados/cenários funciona hoje (importante pra diagnosticar "IA
 
 - O admin pode FIXAR o parâmetro de uma ferramenta no cenário (campo scenario.tool_bindings): quais mídias enviar, qual funil+etapa do card, quais agendas no agendamento. "Deixar a IA decidir" = binding vazio.
 - Quando UM cenário fixa a tool, a execução vira determinística (a IA não escolhe): mídia e kanban são aplicados pós-turno pelo BindingResolver (ordem texto→ação, sem duplicar, idempotente); o agendamento força/restringe a agenda mas a IA ainda define data/hora.
-- Via MCP: scenarios_create/update persiste binding de send_media_asset e create_kanban_item/move_kanban_item (re-escopados por conta). O binding de create_booking NÃO é aceito pela API — pra limitar agendas via MCP, use config.booking_event_type_ids no assistente (captain_assistants_update).
+- Via MCP: scenarios_create/update persiste binding de send_media_asset e create_kanban_item/move_kanban_item (re-escopados por conta). O binding de create_booking NÃO é aceito pela API — pra limitar agendas via MCP, use config.booking_event_type_ids no assistente (captain_assistants_update). **Atualização 15/08:** o modo direto/avulso do create_booking foi REMOVIDO — agenda de Booking é o ÚNICO caminho de agendamento da IA (ver seção "O que mudou no agendamento DA IA").
 - Receita pra criar/editar cenário com binding via MCP (scenarios_create / scenarios_update): (1) o corpo vai SEMPRE embrulhado em `scenario`; (2) a instrução PRECISA mencionar a ferramenta como link markdown `[Rótulo](tool://slug)` — menção crua `(tool://slug)` NÃO conta e o binding é descartado no salvamento; (3) envie `tool_bindings` com o shape: `send_media_asset` → `{ "asset_ids": [Int] }`, `create_kanban_item`/`move_kanban_item` → `{ "funnel_id": Int, "stage": "<chave da etapa>" }`. Não precisa mandar `tools` (é auto-extraído da instrução e sobrescrito). `create_booking` NÃO entra em tool_bindings pela API.
 - Pra APONTAR uma página da base de conhecimento num cenário via MCP, escreva `[@Nome](document://ID)` (o ID numérico do documento) DENTRO do texto da `instruction` — igual ao link de tool, o motor deriva daí o campo `document_ids`. NÃO existe param `document_ids` na API/MCP (mandar seria descartado em silêncio). Teto de 3 documentos; a página apontada ganha PRIORIDADE na busca RAG, NÃO exclusividade (o resto da base continua pesquisável).
 
@@ -445,6 +445,32 @@ criar a campanha e mostre a contagem ao usuário — estimativa e disparo usam o
 - 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).
 
+### O que mudou no agendamento DA IA (2026-08-15)
+
+**1. A IA só agenda por AGENDA de Booking.** `view_booking_option` virou a ÚNICA fonte de horário
+— o modo direto/avulso do `create_booking` foi REMOVIDO (era o único caminho que criava
+compromisso fora do motor de reservas). Consequência prática: a IA passou a respeitar os dias em
+que a agenda NUNCA abre (parou de oferecer domingo) e não inventa mais identificador de agenda —
+com uma única agenda liberada ela assume essa; com duas ou mais, recusa nomeando as válidas. Para
+restringir quais agendas a IA oferece, continua valendo `captain_assistants_update` com
+`config.booking_event_type_ids`.
+
+**2. A IA entrega o link do Meet sozinha.** O link do Google Meet não existe no instante em que o
+agendamento é criado (nasce depois da ida ao Google), e antes a IA prometia o link e nunca voltava.
+Agora o sistema arma uma volta de ~25s; sem link ainda, ele remarca sozinho (+40s) sem gastar turno
+de IA; com link, a IA manda o endereço literal. Se na segunda tentativa o link não veio, ela avisa
+o cliente e aciona um humano (nota privada com menção). Requisitos: o tipo de agendamento precisa
+gerar Meet e o dono da agenda precisa ter o Google conectado. `{{conversation.custom_attribute.meet_link}}`
+e o `{{meet_link}}` da mensagem de confirmação do Booking passaram a vir preenchidos (antes saíam
+vazios) — isso vale inclusive para cliente que não usa IA.
+
+**3. A IA não confirma reunião que não existe.** No último instante antes da resposta virar
+mensagem: se ela afirma agendamento concluído, a agenda está liberada e não há compromisso real na
+conversa, o sistema roda UMA tentativa guiada que agenda de verdade com a data/hora prometidas.
+Agendou, sai a confirmação verdadeira; não agendou, a frase é trocada por uma honesta — nunca
+silêncio. Diagnóstico: se o cliente disser "a IA confirmou e não tem nada na agenda", esse é o
+comportamento ANTIGO (medido: 39 afirmações falsas em 30 dias antes do conserto).
+
 ## Variáveis de conta (account_variables)
 
 Pra dados fixos que se repetem (slogans, endereços, horários):
@@ -685,6 +711,9 @@ automática. Ver a seção de variáveis de conta acima.
    ```
    Cada item de `attachments` é o `blob_id` retornado pelo upload. Pode mandar vários.
 3. O mesmo padrão vale pra anexar mídia num card do Kanban (use o `blob_id` no campo de anexo do card).
+4. **Anexo de MENSAGEM aceita QUALQUER tipo de arquivo (novo 15/08)** — só o TAMANHO reprova. Se
+   houver dúvida sobre um arquivo grande, confira antes com `lionchat_upload_limits_show` (segue
+   sendo a fonte dos tetos).
 
 ## Cuidados com tools de criação
 

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

@@ -471,6 +471,37 @@ pode ser disparado por **webhook externo próprio**: cria-se a integração embu
 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`).
 
+### Disparo de flow por FORMULÁRIO público de captação (2026-08)
+
+Um flow pode ser disparado pelo que o lead faz num **Formulário público** (resource
+`lionchat://docs/formularios-publicos`). São **três gatilhos**, todos no node `start`:
+
+| Gatilho | Quando dispara |
+|---|---|
+| `lead_form_completed` | O lead **concluiu** o formulário |
+| `lead_form_milestone` | O lead **atingiu um marco** dentro do formulário (sem precisar concluir) |
+| `lead_form_abandoned` | O lead **parou no meio** e a janela de abandono do formulário venceu |
+
+Como montar o item do gatilho:
+- **`lead_form_id` é obrigatório** — o gatilho só casa com o formulário apontado; sem ele o flow
+  fica MUDO (nenhum erro, nenhum disparo).
+- Pelo caminho **API/MCP**, `lead_form_id` (e `milestone_node_id`) vão no **topo do item**; a
+  **tela** grava os mesmos campos dentro de `config`. O motor lê os dois formatos — não precisa
+  duplicar.
+- `milestone_node_id` é **opcional** e só existe no `lead_form_milestone`: preenchido, o flow
+  dispara só naquele marco; **vazio = qualquer marco** daquele formulário.
+- Só vale em **flow individual** (`conversation_mode: 'individual'`). Flow de grupo e ferramenta
+  de IA (`ai_tool`) nunca são disparados por formulário.
+
+Comportamento no disparo:
+- Cada gatilho dispara **uma vez por resposta** (`completed`, `milestone:<node_id>` e `abandoned`
+  são chaves independentes) — retentativa não dobra o flow.
+- Exige **contato** na resposta: lead que não deixou nome+telefone não dispara nada. Em caixa
+  WhatsApp (oficial ou QR Code), contato sem telefone também é pulado.
+- O disparo **cria ou reabre uma conversa** na primeira caixa vinculada ao flow — ou seja, acorda
+  os ouvintes de `conversation_created` (automação, outros flows, webhook de saída, Kanban, SLA,
+  notificação). Conte com isso ao desenhar a cadeia.
+
 ### Proteção anti-loop entre motores (2026-06)
 
 Automações e flows podem se encadear (automação dispara flow, flow dispara automação...).
@@ -492,6 +523,11 @@ ficar muda (2026-06-05).
 | `message_created` | Nova mensagem (incoming ou outgoing) |
 | `first_reply_created` | Primeira resposta humana |
 
+**Os gatilhos de Formulário público (`lead_form_completed`, `lead_form_milestone`,
+`lead_form_abandoned`) NÃO entram nessa tabela** — são gatilhos de **flow**, não eventos de
+automação. Não adianta criar `automation_rule` com esses nomes em `event_name`; o caminho é o node
+`start` de um flow (ver a seção acima).
+
 ### Subtipos de `conversation_updated` (campo `action_types`)
 
 Ao criar/atualizar uma `automation_rule` com `event_name: 'conversation_updated'`, envie tambem

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

@@ -502,6 +502,20 @@ MetaLeadIntegration (Facebook Lead Ads)
 ├── status (active/token_expired/paused)
 └── meta_lead_forms (has_many)
 
+LeadForm (Formulário público de captação — feature flag lead_forms, por conta)
+├── account_id (FK)
+├── name / slug (8 chars, gerado na criação e imutável) / display_mode (cards|chat) / active
+├── form_data (jsonb: o desenho do construtor) — published_data (a FOTO publicada, que a página usa)
+├── settings (jsonb: primary_color, theme, abandon_minutes, button_label) / published_at
+└── counts: views / responses / completed (contadores) + lead_form_responses (has_many)
+
+LeadFormResponse (um preenchimento do formulário)
+├── lead_form_id (FK) / account_id (FK)
+├── contact_id (FK opcional — o contato nasce assim que nome+telefone entram, mesmo sem concluir)
+├── status (in_progress / completed / abandoned)
+└── answers (respostas) / milestones (marcos atingidos) / utm_params / started_at / completed_at /
+    abandoned_at
+
 CustomWebhookIntegration (Webhook Universal — entrada)
 ├── account_id (FK)
 ├── name / token (URL única) / active

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

@@ -463,6 +463,12 @@ o botão "Usar variável" ao lado do campo alterna lista fixa ↔ variável.
 
 **Campos NATIVOS do contato (2026-07-29):** com `attr_source: 'contact'`, `attr_key` também aceita os paths canônicos `contact.name`, `contact.email`, `contact.cpf`, `contact.cnpj`, `contact.rg`, `contact.passport`, `contact.date_of_birth`, `contact.gender`, `contact.marital_status`, `contact.profession` e `contact.address.{cep,street,number,complement,neighborhood,city,state,country}` — gravam na ficha nativa do contato (não em custom_attributes). Regras: telefone/identifier/etiquetas NÃO são aceitos (mapa fechado — chave fora dele vira atributo personalizado comum); documentos, nascimento, gênero e **e-mail** só preenchem campo VAZIO; nome/profissão/estado civil/endereço sobrescrevem; valor em branco nunca grava; gênero aceita `m|f|o|na` e estado civil `solteiro|casado|uniao_estavel|divorciado|separado|viuvo`; data de nascimento em `dd/mm/aaaa` ou `aaaa-mm-dd`. Recusas aparecem no histórico de execução (passo 'skipped'/'error' com mensagem).
 
+**Campos NATIVOS do contato em CONDIÇÃO (2026-08-13):** o bloco de Condições e o filtro do gatilho de data passaram a LER os mesmos paths nativos (`contact.name`, `contact.cpf`, `contact.marital_status`, `contact.address.city`, ...) na fonte `contact` — antes só liam atributo personalizado e o campo da ficha voltava vazio, jogando tudo na saída padrão em silêncio. Use com `is_empty`/`is_not_empty` para montar "o CPF está preenchido?". Aceita a forma curta (`contact.cpf`) e a longa (`contact.cadastral.cpf`). **`contact.label` NÃO é aceito** em condição (consulta cara em caminho reativo). **Gênero e estado civil são listas fechadas**: compare com o valor canônico (`m|f|o|na`, `solteiro|casado|uniao_estavel|divorciado|separado|viuvo`) — comparar com "Masculino" nunca casa.
+
+**NÃO use campo nativo na CONDIÇÃO DE SAÍDA nem no gatilho "quando o atributo do contato mudar"** — o sistema só emite o evento de mudança para atributo PERSONALIZADO, então a regra nunca dispararia. Nesses dois lugares o seletor continua oferecendo apenas atributos personalizados, de propósito.
+
+**Parâmetro `always_ask` no node inicial de `ai_tool` (2026-08-13):** `true` faz a IA perguntar o dado ao cliente mesmo que o campo já tenha valor salvo, e regravar com a resposta. Use quando o valor guardado não for confiável (o nome do WhatsApp costuma ser só o primeiro nome). O campo volta a contar como resolvido depois que a IA salvar naquela conversa. Omitir = comportamento de sempre (campo preenchido é pulado).
+
 **Somar/subtrair NÃO é operação dedicada** — é filtro Liquid no próprio `attr_value`. O valor é resolvido como template antes de salvar. Exemplos:
 
 ```json

package/dist/docs/resources/formularios-publicos.md

@@ -0,0 +1,410 @@
+# Formulários Públicos — Guia Profundo
+
+Tudo sobre os Formulários Públicos do LionChat (captação estilo Typeform/Typebot): link público,
+desenho dos blocos, publicação, respostas, funil e integração com fluxos.
+
+## O que é
+
+Um formulário público é uma página de captação hospedada pelo próprio LionChat. O visitante abre um
+link, responde bloco a bloco, e o LionChat cria o contato, guarda as respostas e (opcionalmente)
+dispara um fluxo do FlowBuilder no fim.
+
+- **Link público**: `{FRONTEND_URL}/forms/<referência da conta>/<slug>` — a referência da conta é o
+  `booking_public_slug` (o mesmo usado na agenda pública) e o `slug` do formulário tem 8 caracteres
+  alfanuméricos minúsculos. O campo `public_url` já vem pronto na resposta das tools.
+- **Dois formatos de exibição** (`display_mode`): `cards` (um bloco por tela, estilo Typeform) ou
+  `chat` (bolhas de conversa, estilo Typebot).
+- **Feature flag `lead_forms`, por conta, nasce desligada.** Com a flag desligada a **página pública
+  responde 404** — ninguém consegue preencher. As tools de dashboard (listar, criar, editar,
+  publicar, ver respostas) **funcionam mesmo assim**: não há gate de feature no backend do
+  dashboard. Ou seja: dá pra montar o formulário inteiro antes de ligar a flag, mas não adianta
+  divulgar o link antes.
+- **Escrita é só de administrador.** `create`, `update`, `destroy`, `publish` e `duplicate` passam
+  por `check_admin_authorization?`; usuário não-admin recebe **401**. Leitura (`list`, `show`,
+  `stats`, `responses`) é liberada a qualquer agente da conta.
+
+### Não confundir
+
+| Nome parecido | O que é de verdade |
+|---|---|
+| **Formulário público** (este documento) | Página de captação hospedada pelo LionChat, com blocos e link próprio |
+| **MetaLeadForm** | Formulário de anúncio da Meta (Facebook/Instagram Lead Ads) — outro módulo |
+| **Flow / FlowBuilder** | Motor de automação de conversa. O formulário *dispara* fluxos, mas não é um fluxo |
+
+## Ferramentas disponíveis
+
+| Ferramenta | Endpoint | O que faz |
+|---|---|---|
+| `lionchat_lead_forms_list` | `GET /lead_forms` | Lista os formulários da conta (mais novos primeiro). Não traz `media_urls` |
+| `lionchat_lead_forms_create` | `POST /lead_forms` | Cria. Admin-only |
+| `lionchat_lead_forms_show` | `GET /lead_forms/:id` | Detalhe completo, único lugar que traz `media_urls` |
+| `lionchat_lead_forms_update` | `PATCH /lead_forms/:id` | Edita. Admin-only |
+| `lionchat_lead_forms_destroy` | `DELETE /lead_forms/:id` | Exclui (204 sem corpo). Admin-only |
+| `lionchat_lead_forms_publish` | `POST /lead_forms/:id/publish` | Publica: tira a foto do desenho. Admin-only |
+| `lionchat_lead_forms_duplicate` | `POST /lead_forms/:id/duplicate` | Cópia completa com slug novo. Admin-only |
+| `lionchat_lead_forms_stats` | `GET /lead_forms/:id/stats` | Números e funil por bloco |
+| `lionchat_lead_forms_responses_list` | `GET /lead_forms/:id/responses` | Lista de respostas (leve, sem as respostas em si) |
+| `lionchat_lead_forms_responses_show` | `GET /lead_forms/:id/responses/:rid` | Detalhe de uma resposta, com o que a pessoa respondeu |
+
+**Imagens não têm ferramenta MCP.** O upload de imagem de bloco (`POST /lead_forms/:id/media`,
+máximo 5 MB, só `image/*`) existe no painel. Pela API dá pra referenciar um `image` que já foi
+subido, nunca subir um novo.
+
+## Campos do formulário
+
+| Campo | Tipo | Observação |
+|---|---|---|
+| `name` | string | **Obrigatório** |
+| `display_mode` | string | `cards` (padrão) ou `chat` |
+| `active` | boolean | Formulário inativo devolve 404 na página pública |
+| `form_data` | jsonb | O desenho (rascunho). Teto de 2 MB serializado |
+| `settings` | jsonb | Ver abaixo |
+| `slug` | string | **Gerado no create e imutável** — nunca aceita valor do cliente |
+| `published_at` | timestamp | Quando a foto foi tirada. Nulo = nunca publicado |
+| `public_url` | string | Montado pelo servidor |
+| `counts` | objeto | `{views, responses, completed}` — contadores do banco |
+
+### `settings`
+
+| Chave | Valor | Padrão |
+|---|---|---|
+| `primary_color` | hex | `#7C3AED` |
+| `theme` | `light` ou `dark` (valor fora da lista cai em `light`) | `light` |
+| `abandon_minutes` | inteiro, limitado a 1..1440 | 15 |
+| `button_label` | string — rótulo do botão da página pública | — |
+
+## Ciclo de vida
+
+1. **Criar** com `lionchat_lead_forms_create` (nome + `form_data`, mesmo que mínimo).
+2. **Montar o desenho** em `form_data` (contrato na próxima seção).
+3. **Publicar** com `lionchat_lead_forms_publish` — copia `form_data` para `published_data` e carimba
+   `published_at`.
+4. **Ativar** (`active: true`) e ligar a feature flag `lead_forms` da conta.
+5. **Divulgar** o `public_url`.
+
+**Quem preenche usa SEMPRE a foto publicada, nunca o rascunho.** Editar `form_data` não muda nada
+para quem está preenchendo até um novo `publish`. Isso é de propósito: dá pra mexer no formulário
+com gente respondendo sem quebrar ninguém no meio.
+
+**O contato nasce no MEIO do preenchimento**, não no fim: assim que existem respostas mapeadas para
+`contact.name` E `contact.phone`, o LionChat cria (ou reaproveita) o contato, carimba a origem do
+lead e aplica os atributos personalizados já respondidos. Quem começa e abandona depois disso
+**continua virando contato com as respostas que deu** — é a diferença mais valiosa em relação a um
+formulário tradicional.
+
+## O contrato do `form_data`
+
+Esta é a parte que permite construir formulários pela API. O `form_data` é um desenho de nós e
+arestas:
+
+```json
+{
+  "nodes": [
+    { "id": "n1", "type": "question", "position": { "x": 0, "y": 200 }, "data": { } }
+  ],
+  "edges": [
+    { "id": "e1", "source": "n1", "target": "n2", "sourceHandle": "success" }
+  ]
+}
+```
+
+- `id` de nó e de aresta: qualquer string única dentro do desenho.
+- `position`: `{x, y}` em pixels do canvas. Só afeta a visualização no editor; o motor ignora.
+- `sourceHandle`: **qual saída do nó** a aresta usa. É o que decide o caminho (ver tabela).
+
+### Tipos de bloco
+
+| `type` | Chaves de `data` permitidas | Saídas (`sourceHandle`) | Aparece pro lead? |
+|---|---|---|---|
+| `start` | `title, description, button_label, image` | `success` | sim |
+| `question` | `label, description, field_type, placeholder, required, map_to, scale, image, accept, invalid_message` | `success` | sim |
+| `choice` | `label, description, options, multiple, map_to` | `option_<id da opção>` (escolha única) / `success` (múltipla) | sim |
+| `message` | `title, description, button_label, image` | `success` | sim |
+| `condition` | `branches` | `cond_<id do ramo>` + `else` | não |
+| `action` | `action_type, labels, name, event_name` | `success` | não |
+| `send_message` | `inbox_id, content, template_name, template_params` | `success`, `skipped` | não |
+| `end` | `title, description, redirect_url, button_label, image` | — | sim |
+| `api_request` | `label, url, headers, timeout` | `success`, `error` | não (mostra bloco de espera) |
+| `ai` | `label, mode, prompt, categories, include_answers, model` | modo `generate`: `success`, `error` / modo `classify`: um `cat_<id>` por categoria + `other` | não (mostra bloco de espera) |
+
+**Chave fora da lista não é lida pelo motor** e o editor a **remove no próximo salvamento pela
+tela**. Escrever um campo inventado pela API não gera erro nenhum — ele simplesmente não faz nada e
+depois some. A lista é fonte única (`LeadForm::NODE_DATA_KEYS` no servidor, espelhada em
+`nodeSchema.js` no editor, com spec de contrato comparando as duas).
+
+### Detalhes por chave
+
+**`field_type`** (do `question`): `short_text`, `long_text`, `email`, `phone`, `date`, `number`,
+`rating` (usa `scale`), `url`, `file_upload` (usa `accept`).
+
+**`accept`** (só em `file_upload`): `'any'` ou um array de categorias entre `image`, `video`,
+`audio`, `pdf`, `spreadsheet`, `document`, `xml`. Arquivo executável é recusado sempre, antes de
+qualquer categoria.
+
+**`map_to`**: `''` (não guarda em lugar nenhum), `contact.name`, `contact.email`, `contact.phone`
+ou `custom.<chave de atributo personalizado de contato>`.
+
+**`options`** (do `choice`): `[{ "id": "abc123", "label": "Sim", "image": "" }]`. O `image` por
+opção é o que faz a "escolha com fotos".
+
+**`branches`** (do `condition`): lista avaliada em ordem; nenhum ramo casando cai no handle `else`.
+
+```json
+[{ "id": "b1", "source_node_id": "q_cidade", "operator": "equals", "value": "São Paulo" }]
+```
+
+Operadores: `equals`, `not_equals`, `contains`, `filled`, `not_filled`, `greater_than`,
+`less_than`. Quando a fonte (`source_node_id`) é um `api_request`, o ramo **precisa** de `path` —
+o caminho dentro da resposta da consulta (ex.: `"path": "localidade"`).
+
+**`action_type`**: `add_label` (usa `labels: []`), `milestone` (usa `name` — é o marco que aparece
+no funil e pode disparar fluxo), `meta_pixel_event` e `ga4_event` (usam `event_name`).
+
+**`send_message`**: caixa WhatsApp QR Code usa `content` (texto com variáveis); caixa WhatsApp
+oficial usa `template_name` + `template_params`. Um formulário com `send_message` **obriga** existir
+uma pergunta com `map_to: contact.phone` — sem telefone não há para quem mandar.
+
+**`api_request`**: **só GET**, sem corpo. A `url` precisa ter **domínio literal** (nada de variável
+no host). Variáveis só entram no caminho e nos valores de query. `headers` aceita valor literal ou
+`{{conta.<variável>}}` (o cofre de variáveis da conta) — variável derivada do lead em cabeçalho é
+recusada na publicação. `timeout` em segundos: padrão 8, teto 15.
+
+**`ai`**: `mode` é `generate` (devolve texto em `{{ia.<node_id>}}`) ou `classify` (roteia por
+categoria). `categories` é obrigatório no modo `classify`. `include_answers` (booleano) manda as
+respostas já dadas como contexto. `model` é validado contra a lista suportada
+(`gpt-4.1-nano`, `gpt-4o-mini`, `gpt-4.1-mini`, `gpt-5.4-nano`, `gpt-5.4-mini`, `gpt-4o`, `gpt-4.1`,
+`gpt-5-mini`, `gpt-5.4`, `o3-mini`, `o4-mini`, `gpt-5`, `gpt-5.2`, `gpt-5.5`, `o1`, `o3`);
+`''` = usa o modelo padrão da conta. A IA usa a **chave da própria conta** — conta sem chave faz o
+bloco sair pela saída de erro.
+
+### Variáveis
+
+Usáveis no texto de `send_message`, no `prompt` da IA e na `url` do `api_request`:
+
+| Variável | O que traz | Onde vale |
+|---|---|---|
+| `{{answer.<node_id>}}` | O que a pessoa respondeu naquele bloco (rótulo da opção ou texto) | mensagem, prompt, caminho/query da URL |
+| `{{contact.name}}` `{{contact.phone}}` `{{contact.email}}` | Dados do contato já identificado | mensagem, prompt, caminho/query da URL |
+| `{{api.<node_id>.<caminho>}}` | Um pedaço da resposta de uma consulta | mensagem, prompt, caminho/query da URL |
+| `{{ia.<node_id>}}` | O texto que a IA gerou naquele bloco | mensagem, prompt, caminho/query da URL |
+| `{{conta.<variável>}}` | Variável da conta (cofre, aceita segredo) | **só em cabeçalho de `api_request`** |
+
+Variável desconhecida vira string vazia, em silêncio. `{{conta.*}}` fora do cabeçalho sai vazia
+mesmo que a variável exista — é proteção, não defeito.
+
+## Regras de publicação
+
+`lionchat_lead_forms_publish` devolve **422 com `{errors: [chaves]}`** quando o desenho não passa.
+Cada chave e o que ela quer dizer:
+
+| Chave | Significado |
+|---|---|
+| `no_start` | Não existe bloco `start` no desenho |
+| `start_without_exit` | O `start` não tem aresta saindo dele |
+| `no_reachable_end` | Nenhum bloco `end` é alcançável a partir do `start` |
+| `question_without_label` | Uma pergunta está sem o texto da pergunta |
+| `question_without_exit` | Uma pergunta não tem para onde ir depois |
+| `choice_without_options` | Um bloco de escolha está sem nenhuma opção |
+| `choice_without_exit` | Um bloco de escolha não tem nenhuma saída ligada |
+| `choice_option_without_edge` | Uma opção específica da escolha não leva a lugar nenhum |
+| `condition_without_branches` | Uma condição está sem nenhum ramo configurado |
+| `condition_without_else` | Uma condição não tem a saída "senão" ligada |
+| `action_without_config` | Um bloco de ação está sem a configuração que o tipo dele exige |
+| `send_message_without_inbox` | Um bloco de mensagem está sem caixa de entrada escolhida |
+| `send_message_requires_phone_question` | Há mensagem no formulário mas nenhuma pergunta guarda o telefone |
+| `api_without_url` | Uma consulta está sem endereço |
+| `api_without_error_exit` | Uma consulta está sem a saída de erro ligada |
+| `api_url_host_not_literal` | O domínio da consulta tem variável (só caminho e valores aceitam) |
+| `unknown_variable_in_url` | A URL usa uma variável de família desconhecida |
+| `account_variable_in_url` | A URL usa `{{conta.*}}` (variável da conta só vale em cabeçalho) |
+| `lead_variable_in_header` | Um cabeçalho usa variável vinda do lead (`answer`, `contact`, `api`, `ia`) |
+| `ai_without_prompt` | Um bloco de IA está sem instrução |
+| `ai_without_categories` | Um bloco de IA em modo classificar está sem categorias |
+| `ai_without_error_exit` | Um bloco de IA (modo gerar) está sem a saída de erro ligada |
+| `ai_without_other_exit` | Um bloco de IA (modo classificar) está sem a saída "outros" ligada |
+
+## Tetos e limites
+
+| O quê | Limite |
+|---|---|
+| `form_data` serializado | 2 MB |
+| Valor de uma resposta | 4 KB |
+| Passos por requisição (anti-loop) | 50 |
+| `days` em `stats` e `responses` | máximo 90 (valor ≤ 0 vira 30) |
+| Página de `responses` | 25 por página, fixo; `page` até 10.000 |
+| Chamadas de IA | 300 por formulário/dia, 1.000 por conta/dia, 10 por resposta |
+| Consultas (`api_request`) | 2.000 por formulário/dia, 10.000 por conta/dia |
+| Arquivo enviado pelo lead | 10 MB por arquivo, 10 arquivos por resposta |
+| Imagem de bloco (só pelo painel) | 5 MB, apenas `image/*` |
+| Funil em `stats` | 50.000 respostas (acima disso o funil sai parcial) |
+
+## Respostas e funil
+
+**`lionchat_lead_forms_stats`** (`days` opcional) devolve:
+
+```json
+{ "views": 320, "starts": 180, "completed": 96, "abandoned": 40, "completion_rate": 53,
+  "funnel": [{ "node_id": "q_nome", "type": "question", "label": "Qual é o seu nome?",
+               "reached": 175, "percent": 97 }],
+  "milestones": [{ "node_id": "n7", "name": "Qualificado", "reached": 62 }] }
+```
+
+O funil só lista os blocos que a pessoa vê (`start`, `question`, `choice`, `message`, `end`), na
+ordem do desenho **publicado**.
+
+**`lionchat_lead_forms_responses_list`** aceita `status` (`in_progress`, `completed` ou `abandoned`;
+valor fora da lista é ignorado), `days` e `page`. A lista **nunca** traz as respostas em si — só
+`{id, status, contact, current_node_label, answered_count, created_at, completed_at}`.
+
+**`lionchat_lead_forms_responses_show`** traz o conteúdo:
+
+- `answers`: `[{label, value_label, at, download_url?}]` — o `download_url` só existe em resposta de
+  envio de arquivo (e vem nulo se o arquivo já foi apagado).
+- `milestones`: os marcos que a pessoa atingiu.
+- `effects`: o resultado dos blocos de consulta e de IA — `{node_id, label, state, error, status,
+  url_short, at}`. `state` é `pending`, `done` ou `error`. **`url_short` é esquema + host + caminho,
+  sem a query**; o valor enviado, os cabeçalhos e o prompt **nunca** saem pela API.
+- `utm_params`: de onde o lead veio.
+
+Motivos de erro que aparecem em `effects`: `http_<código>`, `timeout`, `ssrf_blocked`,
+`invalid_url`, `result_too_large`, `stale`, `busy`, `budget_exceeded`, `no_ai_key`, `ai_error`,
+`unresolved_variable`.
+
+## Receitas
+
+### 1. Formulário simples que já publica
+
+Desenho mínimo que passa na publicação: início, nome, telefone, fim.
+
+```json
+{
+  "nodes": [
+    { "id": "start", "type": "start", "position": { "x": 0, "y": 0 },
+      "data": { "title": "Fale com a gente", "description": "Leva 30 segundos.",
+                "button_label": "Começar" } },
+    { "id": "q_nome", "type": "question", "position": { "x": 0, "y": 200 },
+      "data": { "label": "Qual é o seu nome?", "field_type": "short_text",
+                "required": true, "map_to": "contact.name" } },
+    { "id": "q_fone", "type": "question", "position": { "x": 0, "y": 400 },
+      "data": { "label": "Qual é o seu WhatsApp?", "field_type": "phone",
+                "required": true, "map_to": "contact.phone" } },
+    { "id": "fim", "type": "end", "position": { "x": 0, "y": 600 },
+      "data": { "title": "Obrigado!", "description": "Já falamos com você." } }
+  ],
+  "edges": [
+    { "id": "e1", "source": "start", "target": "q_nome", "sourceHandle": "success" },
+    { "id": "e2", "source": "q_nome", "target": "q_fone", "sourceHandle": "success" },
+    { "id": "e3", "source": "q_fone", "target": "fim", "sourceHandle": "success" }
+  ]
+}
+```
+
+Mande isso em `lionchat_lead_forms_create` junto com `name`, depois
+`lionchat_lead_forms_publish` e `lionchat_lead_forms_update` com `active: true`.
+
+### 2. Consultar o CEP e ramificar pela cidade
+
+Pergunta o CEP, consulta o ViaCEP e manda quem é de São Paulo para um caminho diferente.
+Fragmento — os blocos `start`, `msg_sp`, `msg_outros`, `fim_erro` e os fins ficam de fora por
+brevidade; no envio real todos precisam existir e alcançar um bloco de fim.
+
+```json
+{
+  "nodes": [
+    { "id": "q_cep", "type": "question", "position": { "x": 0, "y": 200 },
+      "data": { "label": "Qual é o seu CEP?", "field_type": "short_text", "required": true } },
+    { "id": "api_cep", "type": "api_request", "position": { "x": 0, "y": 400 },
+      "data": { "label": "Consulta de CEP",
+                "url": "https://viacep.com.br/ws/{{answer.q_cep}}/json/",
+                "headers": [], "timeout": 8 } },
+    { "id": "cond_sp", "type": "condition", "position": { "x": 0, "y": 600 },
+      "data": { "branches": [ { "id": "b1", "source_node_id": "api_cep",
+                                "path": "localidade", "operator": "equals",
+                                "value": "São Paulo" } ] } }
+  ],
+  "edges": [
+    { "id": "e1", "source": "q_cep", "target": "api_cep", "sourceHandle": "success" },
+    { "id": "e2", "source": "api_cep", "target": "cond_sp", "sourceHandle": "success" },
+    { "id": "e3", "source": "api_cep", "target": "fim_erro", "sourceHandle": "error" },
+    { "id": "e4", "source": "cond_sp", "target": "msg_sp", "sourceHandle": "cond_b1" },
+    { "id": "e5", "source": "cond_sp", "target": "msg_outros", "sourceHandle": "else" }
+  ]
+}
+```
+
+Três coisas obrigatórias aqui: a saída `error` ligada, o `else` ligado, e o `path` no ramo (porque a
+fonte é uma consulta). Faltando qualquer uma, a publicação recusa.
+
+### 3. Triagem por IA
+
+Classifica o que a pessoa escreveu e manda cada caso para um lugar.
+
+```json
+{
+  "nodes": [
+    { "id": "q_motivo", "type": "question", "position": { "x": 0, "y": 200 },
+      "data": { "label": "Conte rapidinho o que você precisa",
+                "field_type": "long_text", "required": true } },
+    { "id": "ia_triagem", "type": "ai", "position": { "x": 0, "y": 400 },
+      "data": { "label": "Triagem", "mode": "classify",
+                "prompt": "Classifique o pedido do cliente em uma das categorias.",
+                "categories": [ { "id": "c1", "label": "Orçamento" },
+                                { "id": "c2", "label": "Suporte" } ],
+                "include_answers": true, "model": "" } }
+  ],
+  "edges": [
+    { "id": "e1", "source": "q_motivo", "target": "ia_triagem", "sourceHandle": "success" },
+    { "id": "e2", "source": "ia_triagem", "target": "fim_orcamento", "sourceHandle": "cat_c1" },
+    { "id": "e3", "source": "ia_triagem", "target": "fim_suporte", "sourceHandle": "cat_c2" },
+    { "id": "e4", "source": "ia_triagem", "target": "fim_geral", "sourceHandle": "other" }
+  ]
+}
+```
+
+Enquanto a consulta ou a IA roda, o lead vê um bloco de espera — o formulário não trava nem perde a
+sessão.
+
+### 4. Disparar um fluxo quando o formulário for concluído
+
+O gatilho mora no **fluxo**, não no formulário. Use `lionchat_flows_create` ou
+`lionchat_flows_update` e coloque o item no bloco de início:
+
+```json
+{ "key": "lead_form_completed", "lead_form_id": 12 }
+```
+
+Três gatilhos existem:
+
+| `key` | Quando dispara |
+|---|---|
+| `lead_form_completed` | A pessoa chegou ao bloco de fim |
+| `lead_form_milestone` | A pessoa passou por um bloco de ação do tipo `milestone` |
+| `lead_form_abandoned` | A pessoa parou de responder e passou o tempo de `abandon_minutes` |
+
+No `lead_form_milestone` dá pra acrescentar `milestone_node_id` para mirar um marco específico; sem
+ele, qualquer marco daquele formulário dispara. O `lead_form_id` (e o `milestone_node_id`) podem ir
+no topo do item ou dentro de `config` — o motor lê os dois.
+
+**O gatilho só dispara se a resposta já tiver contato**, ou seja, se nome e telefone foram
+respondidos. E dispara uma vez só por resposta e por tipo. O fluxo recebe as respostas como
+variáveis: `form_name`, `form_kind`, `form_milestone` e uma variável `form_<pergunta>` por resposta
+dada.
+
+## Armadilhas
+
+- **O `slug` é gerado e imutável.** Mandar `slug` no create ou no update não faz nada. Link
+  publicado nunca muda de endereço.
+- **`published_data` nunca sai pela API.** Para saber o que está no ar, olhe `published_at` e
+  compare mentalmente com o `form_data` — não existe endpoint que devolva a foto.
+- **`form_data` no update SUBSTITUI o desenho inteiro.** Não há merge. Leia com
+  `lionchat_lead_forms_show`, altere o que precisa e mande o desenho completo de volta. Mandar só os
+  nós novos apaga todo o resto.
+- **A cópia nasce desligada e não publicada.** `duplicate` cria com `active: false`, sem
+  `published_at`, com `" (cópia)"` no nome e slug novo. As imagens são duplicadas de verdade (blobs
+  novos), então mexer nelas na cópia não afeta o original.
+- **Publicar não ativa.** São dois passos: `publish` (tira a foto) e `update` com `active: true`.
+- **Flag desligada = página 404.** Se o cliente diz que o link não abre e as tools funcionam
+  normalmente, o suspeito número um é a feature `lead_forms` da conta.
+- **`media_urls` só existe no `show`.** A listagem não traz, de propósito (payload).
+- **Nunca escreva segredo em cabeçalho literal** de `api_request` — use `{{conta.<variável>}}`, que
+  resolve só no servidor e nunca aparece na tela nem no log.