@lionchat/mcp-server 1.12.1 → 1.14.0

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

@@ -0,0 +1,499 @@
+# Formulários Públicos — Guia Profundo
+
+Tudo sobre os Formulários Públicos do LionChat (captação estilo Typeform/Typebot): link público,
+caixa de WhatsApp vinculada, desenho dos blocos, publicação, respostas, funil, simulador e
+integração com fluxos. Atualizado em 18/08/2026 (v4.10.226).
+
+## 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, abre a conversa na
+caixa de WhatsApp vinculada 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 da agenda pública). O `slug` do formulário nasce sorteado (8
+  caracteres) e **pode ser trocado** (ver Campos). O campo `public_url` já vem pronto na resposta.
+- **Caixa de WhatsApp vinculada é OBRIGATÓRIA para publicar** (`inbox_id`). Só canais
+  `Channel::Whatsapp` (oficial) e `Channel::Waha` (QR Code). É por ela que o bloco Enviar mensagem
+  dispara e que a conversa do lead nasce.
+- **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, simular) **funcionam mesmo assim**. Dá pra montar tudo antes de ligar a
+  flag; não adianta divulgar o link antes.
+- **Escrita é só de administrador.** `create`, `update`, `destroy`, `publish`, `duplicate` e
+  `check_embed` passam por `check_admin_authorization?`; usuário não-admin recebe **401**. Leitura
+  (`list`, `show`, `stats`, `responses`) e o **simulador** (`test_run`) são liberados 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 (inclusive `inbox_id` e `slug`). 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 (com a caixa dentro). Admin-only |
+| `lionchat_lead_forms_duplicate` | `POST /lead_forms/:id/duplicate` | Cópia completa com slug novo (copia o `inbox_id`). 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 |
+| `lionchat_lead_forms_test_run` | `POST /lead_forms/:lead_form_id/test_runs` | Simulador: roda o RASCUNHO no motor real, sem deixar rastro. Qualquer agente da conta |
+| `lionchat_lead_forms_check_embed` | `POST /lead_forms/check_embed` | Confere se um site aceita ser exibido em iframe (bloco Página externa). Admin-only |
+
+**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 |
+| `inbox_id` | integer | Caixa de WhatsApp vinculada. Obrigatória para publicar. Ver regras abaixo |
+| `form_data` | jsonb | O desenho (rascunho). Teto de 2 MB serializado |
+| `settings` | jsonb | Ver abaixo |
+| `slug` | string | **Editável** em create e update. Normalizado no servidor (acento vira letra, resto vira hífen), 3 a 60 caracteres, minúsculas + números + hífen, único dentro da conta. Vazio/só espaços = mantém o atual (não é erro). Duplicado = 422. Ausente no create = sorteia 8 caracteres |
+| `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 |
+
+**A resposta de `show`/`list`/`create`/`update` traz também:** `inbox` (`{id, name, channel_type}`
+ou `null` — a caixa resolvida), e `published_inbox_id` (a caixa que está NA FOTO publicada).
+
+### Regras do `inbox_id`
+
+- Caixa que não é da conta → 422 `{errors: {inbox_id: ["not found in this account"]}}`.
+- Canal fora de `Channel::Whatsapp`/`Channel::Waha` → `["channel not supported"]`.
+- **Trocar de caixa pode; trocar de TIPO de canal não** → `["channel type cannot change"]`.
+  Os blocos foram montados pro canal atual (oficial exige modelo aprovado; QR aceita texto livre e
+  mídia). Formulário que ainda não tinha caixa escolhe livremente.
+- **A troca só vale depois de republicar**: `publish` grava o `inbox_id` DENTRO da foto
+  (`published_data`), e o motor lê sempre a foto.
+
+### `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..15 (minutos) | 15 |
+| `button_label` | string — rótulo do botão da página pública | — |
+| `resume` | booleano — continuar de onde parou entre visitas | `true` |
+| `chat_avatar` | id numérico de blob já subido (`media`) — foto redonda ao lado dos balões, só no formato `chat`. O público recebe `chat_avatar_url` resolvida (nunca o id) | — |
+
+## Ciclo de vida
+
+1. **Criar** com `lionchat_lead_forms_create` (nome + `form_data`, mesmo que mínimo).
+2. **Vincular a caixa de WhatsApp** (`inbox_id`) — sem ela a publicação recusa (`form_without_inbox`).
+3. **Montar o desenho** em `form_data` (contrato na próxima seção). Todo formulário precisa de uma
+   pergunta com `map_to: contact.phone` (`form_requires_phone_question`).
+4. **Testar** com `lionchat_lead_forms_test_run` — roda o rascunho de verdade, sem sujar nada.
+5. **Publicar** com `lionchat_lead_forms_publish` — copia `form_data` (+ `inbox_id`) para
+   `published_data` e carimba `published_at`.
+6. **Ativar** (`active: true`) e ligar a feature flag `lead_forms` da conta.
+7. **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`.
+
+**O contato nasce em TRÊS momentos**: quando a pessoa conclui, quando a resposta é marcada como
+abandonada (padrão e teto de 15 minutos sem atividade), ou logo antes de um bloco de Enviar
+WhatsApp. Enquanto isso nada é criado — nem contato, nem conversa, nem card. Efeitos que dependem de
+contato (evento de pixel, gatilho de marco) ficam guardados e disparam no nascimento, com a hora
+original de cada etapa. Quando o contato nasce ali, a conversa começa com uma pílula dizendo qual
+formulário o originou. Contato apagado no painel solta o vínculo — a resposta pode renascer no
+próximo momento. Os textos `{{contact.name}}`/`{{contact.phone}}`/`{{contact.email}}` saem do que a
+pessoa RESPONDEU, não da ficha.
+
+### Link identificado (pula perguntas já conhecidas)
+
+Toda mensagem de TEXTO enviada numa conversa que contenha um link `/forms/` sai **carimbada
+automaticamente** com `?lt_form=<código>` (sem depender de LionTrack; vale pra mensagem de flow e
+de IA também; nunca em grupo). Quem abre o link carimbado tem a resposta ligada ao contato desde o
+início, e o formulário **PULA as perguntas de identidade que já têm valor** — só as três nativas:
+nome, telefone e e-mail. A resposta pulada é gravada com o valor da ficha e o selo `prefilled`.
+
+Seguranças: o valor pulado **nunca aparece na tela nem no payload público**, e o botão Voltar **não
+alcança** a pergunta pulada. Código de outra conta, contato apagado ou qualquer pane = o formulário
+roda anônimo normal. Link copiado do editor e colado fora de uma conversa NÃO tem carimbo.
+
+## O contrato do `form_data`
+
+```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, video_url` | `success` | sim |
+| `question` | `label, description, field_type, placeholder, required, map_to, scale, image, video_url, 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, video_url` | `success` | sim |
+| `condition` | `branches` | `cond_<id do ramo>` + `else` | não |
+| `action` | `items, label` (+ formato antigo `action_type, labels, name, event_name`) | `success` | não |
+| `send_message` | `messageItems` (+ formato antigo `content, template_name, template_params`) | `success`, `skipped` | não |
+| `booking` | `label, description, event_type_id, required` | `success` (agendou) + `no_booking` (seguiu sem agendar; some quando `required`) | sim |
+| `set_variable` | `label, assignments` | `success` | não |
+| `embed` | `title, description, url, height, button_label, embed_allowed, show_open_external` | `success` | sim |
+| `end` | `title, description, redirect_url, button_label, image, video_url` | — | sim |
+| `api_request` | `label, method, url, headers, body, 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`, `time`,
+`datetime`, `number`, `rating` (usa `scale`), `url`, `file_upload` (usa `accept`), e os documentos
+com validação de verdade: `cpf`, `cnpj`, `cep` (dígito verificador/8 dígitos; gravam só números;
+erros `invalid_cpf`/`invalid_cnpj`/`invalid_cep`).
+- `time` grava `HH:MM` (24h; erro `invalid_time`).
+- `datetime` grava `AAAA-MM-DDTHH:MM` — hora local de quem preencheu, SEM fuso; o fuso de leitura é
+  o da definição do atributo de destino (erro `invalid_datetime`).
+
+**`video_url`** (em `start`, `question`, `message`, `end`): link de YouTube, Vimeo ou arquivo de
+vídeo direto. Com vídeo válido, ele ocupa o lugar da imagem. Link fora do formato conhecido não
+renderiza e não dá erro.
+
+**`accept`** (só em `file_upload`): `'any'` ou um array de categorias entre `image`, `video`,
+`audio`, `pdf`, `spreadsheet`, `document`, `xml`. Arquivo executável é recusado sempre.
+
+**`map_to`** — para onde vai a resposta:
+- `''` — não guarda em lugar nenhum (só em `answers`).
+- `contact.name`, `contact.email`, `contact.phone` — os três nativos.
+- `contact.cadastral.<campo>` — `cpf`, `rg`, `cnpj`, `passport`, `profession`, `marital_status`,
+  `gender`, `date_of_birth` (os dois últimos sem tela; funcionam por API e são normalizados:
+  "solteira" vira `solteiro`, "masculino" vira `m`).
+- `contact.address.<campo>` — `cep`, `street`, `number`, `complement`, `neighborhood`, `city`,
+  `state`, `country`.
+- `custom.<chave>` — atributo personalizado de CONTATO.
+- `conversation_custom.<chave>` — atributo personalizado da CONVERSA (só chave definida na conta;
+  coerção de tipo; teto 1500 caracteres).
+- **Lista de recusa no servidor** (o valor é pulado de forma visível, sem erro): `name`, `email`,
+  `phone_number`, `identifier`, `card` e chaves começando com `captain_`, `eclinica_`, `origin_`,
+  `lt_`, `booking_`, `waha_`, `whatsapp_`, `ctwa_`, `meta_lead_`.
+- Contato pré-existente recebe valor **só em campo vazio** — exceto o que ESTA resposta gravou e
+  ninguém mudou depois (correção via Voltar).
+
+**`options`** (do `choice`): `[{ "id": "abc123", "label": "Sim", "image": "" }]`.
+
+**`branches`** (do `condition`): lista avaliada em ordem; nenhum ramo casando cai no handle `else`.
+Operadores: `equals`, `not_equals`, `contains`, `filled`, `not_filled`, `greater_than`,
+`less_than`. Fonte `api_request` exige `path` (caminho dentro da resposta).
+
+**`items`** (do `action`) — o formato novo, uma LISTA de ações `[{key, config}]`:
+
+| `key` | `config` mínimo para publicar | O que faz |
+|---|---|---|
+| `update_contact_attribute` | `attr_key` | Grava atributo personalizado do CONTATO |
+| `update_conversation_attribute` | `attr_key` | Grava atributo personalizado da CONVERSA |
+| `add_label` | `labels` com ≥1 título | Etiqueta o contato |
+| `milestone` | `name` | Marco do funil (pode disparar fluxo) |
+| `meta_pixel_event` | `event_name` | Evento Meta CAPI (`[a-zA-Z0-9_]`, até 40) |
+| `ga4_event` | `event_name` | Evento GA4 |
+
+O `config` das ações de atributo aceita também `attr_value` (texto com variáveis) e `attr_op`:
+`set` (sobrescrever, padrão), `plus`, `minus`, `times`, `divided_by`. **A conta é feita no
+servidor** sobre o valor atual, com trava de repetição (roda UMA vez por preenchimento); valor que
+não vira número não grava; divisão por zero não grava. A operação aritmética é a única que passa
+por cima do "só grava em campo vazio". Identidade (nome/telefone/e-mail) NÃO se grava por aqui.
+Formato antigo (`action_type` + campos soltos) continua sendo lido.
+
+**`messageItems`** (do `send_message`) — LISTA de mensagens, enviadas na ordem:
+- `{type: "text", content: "..."}` — texto com variáveis (caixa QR).
+- `{type: "whatsapp_template" | "template", template_params: {name, category, language, namespace,
+  processed_params}}` — modelo aprovado (caixa oficial; `language` padrão `pt_BR`).
+- `{type: "image" | "video" | "audio" | "file" | "document" | "attachment" | "url_media",
+  url | file_url | blob_signed_id, caption}` — mídia.
+Item que falha **não derruba os outros** — vira `skipped_item {index, reason}` em `answers`.
+A caixa é a DO FORMULÁRIO (`inbox_id`) — o bloco não tem caixa própria. Formato antigo
+(`content`/`template_name`/`template_params` soltos) continua sendo lido.
+
+**`booking`** — calendário DENTRO do formulário:
+- `event_type_id` = id de um tipo de evento de Agendamento da conta (ativo).
+- `required: true` = só avança depois de agendar (a saída `no_booking` some do desenho).
+- O payload público leva `booking` (slug público, título, duração, `task_type`, `ask_email`,
+  `ask_description`), `prefill` (nome/telefone/e-mail já respondidos) e `missing` (o que o tipo
+  exige e o formulário não perguntou — e-mail só quando `task_type` é `video_call`). O id interno
+  do tipo NUNCA sai. Tipo apagado/desativado depois de publicado: a tela mostra "indisponível" com
+  botão de continuar (o `required` é liberado — ninguém fica preso).
+- O valor gravado na resposta é o id do agendamento criado (validado contra a conta).
+
+**`set_variable`** — cria variáveis temporárias da resposta (invisível pro lead):
+- `assignments: [{key, value}]` — até 20 linhas, 1000 caracteres por valor; `key` vira
+  `{{var.<key>}}` nos blocos seguintes. Linha com `key` vazia é ignorada.
+- SÓ variável. Gravar em contato/conversa é papel do bloco de Ações (um `target` em um item é
+  ignorado pelo motor e descartado pela tela).
+
+**`embed`** — "Página externa", um site de fora exibido DENTRO do formulário (checkout, simulador,
+agenda externa):
+- `url` precisa começar com `https://` LITERAL (variável só do meio pra frente). Na montagem, as
+  variáveis resolvem por posição, com codificação de URL, e o https é reconferido — URL que não
+  for https sai VAZIA do payload (proteção contra script via variável).
+- `embed_allowed` NÃO é configuração sua: é o veredito de `lionchat_lead_forms_check_embed`
+  gravado no desenho (`true`/`false`/`null`). Com `false`, a página mostra o aviso educado + botão
+  "Abrir em nova página" em vez de um quadrado vazio. Escrever `true` na mão mente pro renderizador.
+- `height` em pixels (padrão 480, limitado 240..1200). `show_open_external` (padrão `true`) mostra
+  o botão de abrir fora; com o site recusando o iframe, o botão aparece mesmo desligado — é a
+  única saída da pessoa.
+- O bloco avança por botão (a página embutida é caixa fechada — não dá pra saber quando um
+  pagamento terminou lá dentro). Checkout é justamente o tipo de página que MAIS recusa iframe.
+
+**`api_request`**: `method` aceita `GET`, `POST`, `PUT`, `PATCH`, `DELETE` (padrão `GET`). `body`
+(até 64 KB) aceita variáveis — inclusive `{{conta.<variável>}}`; valor do lead entra escapado em
+corpo JSON. A `url` precisa ter **domínio literal** (variáveis só no caminho e nos valores de
+query; `{{conta.*}}` NÃO vale na URL). `headers` aceita literal ou `{{conta.<variável>}}` —
+variável 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; `''` = 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
+
+| 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, valores do bloco, URL/corpo de consulta |
+| `{{contact.name}}` `{{contact.phone}}` `{{contact.email}}` | O que a pessoa respondeu (a ficha é reserva) | idem |
+| `{{api.<node_id>.<caminho>}}` | Um pedaço da resposta de uma consulta | idem |
+| `{{ia.<node_id>}}` | O texto que a IA gerou naquele bloco | idem |
+| `{{var.<nome>}}` | Variável criada pelo bloco Definir variável | idem |
+| `{{conta.<variável>}}` | Variável da conta (cofre) | cabeçalho e CORPO de `api_request` (com segredo); em `set_variable` e no valor das Ações só as NÃO-secretas |
+
+Variável desconhecida vira string vazia, em silêncio. `{{conta.*}}` em texto público sai vazia
+mesmo que exista — é proteção, não defeito.
+
+## Regras de publicação
+
+`lionchat_lead_forms_publish` devolve **422 com `{errors: [chaves]}`**. As 34 chaves atuais:
+
+| Chave | Significado |
+|---|---|
+| `no_start` | Não existe bloco `start` |
+| `start_without_exit` | O `start` não tem aresta saindo |
+| `no_reachable_end` | Nenhum `end` alcançável a partir do `start` |
+| `form_without_inbox` | O formulário não tem caixa de WhatsApp válida vinculada |
+| `form_requires_phone_question` | Nenhuma pergunta guarda o telefone (`map_to: contact.phone`) — obrigatória em TODO formulário |
+| `question_without_label` | Pergunta sem o texto |
+| `question_without_exit` | Pergunta sem saída |
+| `choice_without_options` | Escolha sem opções |
+| `choice_without_exit` | Escolha sem nenhuma saída ligada |
+| `choice_option_without_edge` | Uma opção específica não leva a lugar nenhum |
+| `condition_without_branches` | Condição sem ramos |
+| `condition_without_else` | Condição sem o "senão" ligado |
+| `action_without_config` | Bloco de ação sem nenhum item completo |
+| `send_message_official_without_template` | Caixa OFICIAL vinculada e o bloco de mensagem sem nenhum modelo |
+| `send_message_qr_without_content` | Caixa QR vinculada e o bloco de mensagem sem nenhum item que entregue algo |
+| `api_without_url` | Consulta sem endereço |
+| `api_without_error_exit` | Consulta sem a saída de erro ligada |
+| `api_url_host_not_literal` | O domínio da consulta tem variável |
+| `api_method_invalid` | `method` fora de GET/POST/PUT/PATCH/DELETE |
+| `unknown_variable_in_url` | A URL usa variável de família desconhecida |
+| `unknown_variable_in_body` | O corpo usa variável de família desconhecida (ou `{{` malformado) |
+| `account_variable_in_url` | A URL usa `{{conta.*}}` (só cabeçalho e corpo aceitam) |
+| `lead_variable_in_header` | Cabeçalho usa variável vinda do lead |
+| `ai_without_prompt` | IA sem instrução |
+| `ai_without_categories` | IA em modo classificar sem categorias |
+| `ai_without_error_exit` | IA (gerar) sem a saída de erro |
+| `ai_without_other_exit` | IA (classificar) sem a saída "outros" |
+| `booking_without_event_type` | Agendamento sem tipo de evento escolhido |
+| `booking_event_type_invalid` | O tipo não é da conta ou está desativado |
+| `booking_without_exit` | Agendamento sem a saída "agendou" ligada |
+| `set_variable_without_assignments` | Definir variável sem nenhuma linha com nome |
+| `set_variable_without_exit` | Definir variável sem saída |
+| `embed_without_url` | Página externa sem endereço |
+| `embed_url_not_https` | O endereço da Página externa não começa com `https://` literal |
+
+**Não existem mais** (renomeadas em 16/08): `send_message_without_inbox` →
+`form_without_inbox`; `send_message_requires_phone_question` → `form_requires_phone_question`.
+
+## 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; corpo até 64 KB |
+| 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) |
+| Itens do bloco de Ações / linhas do Definir variável | 20 cada; 1000 caracteres por valor |
+| Respostas por chamada do simulador | 60 |
+| Altura da Página externa | 240..1200 px |
+| Conferência de embed | 5 s por salto, até 3 redirecionamentos |
+
+## Simulador (`lionchat_lead_forms_test_run`)
+
+Roda o **rascunho** (`form_data`, não a foto) no motor de verdade e desfaz tudo no fim — nada fica
+no banco: sem contato, sem conversa, sem WhatsApp, sem pixel, sem resposta nos relatórios. Não
+exige admin. O estado do teste vive em quem chama: cada chamada reproduz o teste inteiro a partir
+da lista de respostas.
+
+- Body: `{answers: [{node_id, value}]}` — até 60 itens; vazio = começa do início. Item cujo
+  `node_id` não é o bloco atual PARA a reprodução ali (devolve o bloco onde parou).
+- Resposta 200: `{block, log, answers, variables, form}` — `block` é o mesmo envelope da página
+  pública; `log` é o caminho percorrido (`[{node_id, type, label, answer, detail}]` — o `detail`
+  mostra variável criada, ações executadas, resultado de consulta/IA e o rumo das condições).
+- 422: `{error: "invalid_value", reason}` (uma resposta reprovada na validação) ou
+  `{error: "test_run_failed", reason}`.
+
+## Respostas e funil
+
+**`lionchat_lead_forms_stats`** (`days` opcional) devolve views/starts/completed/abandoned/
+completion_rate + `funnel` por bloco + `milestones`. O funil lista os blocos que a pessoa vê
+(`start`, `question`, `choice`, `message`, `booking`, `embed`, `end`), na ordem do desenho
+**publicado**.
+
+**`lionchat_lead_forms_responses_list`** aceita `status` (`in_progress`, `completed`,
+`abandoned`), `days` e `page`. A lista nunca traz as respostas em si — só `{id, status, contact,
+current_node_label, answered_count, created_at, completed_at}`. **`contact` pode vir
+`{id: null, name, phone, pending: true}`** — é quem ainda está preenchendo (o contato só nasce nos
+três momentos); nome e telefone saem do que a pessoa já digitou.
+
+**`lionchat_lead_forms_responses_show`** traz o conteúdo:
+
+- `answers`: `[{label, value_label, at, download_url?}]`. **Atenção:** o bloco de Ações grava
+  entradas SINTÉTICAS com chave `"<node_id>::<n>"` — nem toda chave de `answers` é id de bloco.
+- `conversation`: `{id, display_id}` ou `null` — a conversa aberta na caixa vinculada.
+- `milestones`: os marcos atingidos.
+- `effects`: resultado de consulta/IA — `{node_id, label, state, error, status, url_short, at}`.
+  `url_short` é esquema + host + caminho, sem a query; corpo, cabeçalhos e prompt nunca saem.
+- `utm_params`: de onde o lead veio.
+
+Motivos de erro em `effects`: `http_<código>`, `timeout`, `ssrf_blocked`, `invalid_url`,
+`result_too_large`, `stale`, `busy`, `budget_exceeded`, `no_ai_key`, `ai_error`,
+`unresolved_variable`.
+
+## Conferência de iframe (`lionchat_lead_forms_check_embed`)
+
+Body `{url}`. Resposta `{status, reason}`:
+
+| `status` | `reason` | Significado |
+|---|---|---|
+| `allowed` | — | O site aceita ser exibido dentro do formulário |
+| `blocked` | `not_https` | URL não começa com https:// |
+| `blocked` | `x_frame_options` / `frame_ancestors` | O site declara que recusa iframe |
+| `blocked` | `url_blocked` | Endereço bloqueado por segurança (rede interna etc.) |
+| `unknown` | `unreachable` / `http_<código>` | Não deu pra conferir — a página tenta o iframe e o botão de abrir fora cobre |
+
+O veredito deve ser gravado em `embed_allowed` do bloco. Sites de checkout são os que mais recusam.
+
+## Receitas
+
+### 1. Formulário simples que já publica
+
+Início, nome, telefone, fim — E a caixa vinculada:
+
+```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` e um `inbox_id` de caixa WhatsApp,
+depois `lionchat_lead_forms_publish` e `lionchat_lead_forms_update` com `active: true`.
+
+### 2. Consultar o CEP e ramificar pela cidade
+
+Igual à receita clássica: pergunta o CEP, consulta o ViaCEP (`method` pode ficar de fora — GET é o
+padrão) e ramifica com `path` no ramo cuja fonte é a consulta. Obrigatórios: saída `error` ligada,
+`else` ligado e o `path`.
+
+### 3. Triagem por IA
+
+`mode: "classify"` + `categories` + arestas `cat_<id>` e `other`. Inalterado.
+
+### 4. Disparar um fluxo quando o formulário for concluído
+
+O gatilho mora no **fluxo**: `{ "key": "lead_form_completed", "lead_form_id": 12 }` no bloco de
+início do flow. Três gatilhos: `lead_form_completed`, `lead_form_milestone` (aceita
+`milestone_node_id`), `lead_form_abandoned`. O `lead_form_id` pode ir no topo do item ou em
+`config`. **O gatilho só dispara depois que o contato nasce** — antes fica guardado. O fluxo
+recebe `form_name`, `form_kind`, `form_milestone` e uma variável `form_<pergunta>` por resposta.
+
+### 5. Agendamento dentro do formulário
+
+```json
+{ "id": "agenda", "type": "booking", "position": { "x": 0, "y": 500 },
+  "data": { "label": "Escolha um horário", "event_type_id": "34", "required": false } }
+```
+
+Ligue `success` (obrigatória) pro caminho de quem agendou e `no_booking` pro de quem seguiu sem
+agendar (com `required: true` essa saída deixa de existir). O tipo de evento vem de
+`lionchat_booking_event_types_list`.
+
+## Armadilhas
+
+- **O `slug` é EDITÁVEL** (mudou em 16/08). Trocar o slug derruba os links já divulgados —
+  inclusive os já enviados em mensagens. Vazio mantém o atual; duplicado dá 422.
+- **`inbox_id` só troca por caixa do MESMO tipo de canal** (`channel type cannot change`), e a
+  troca só vale ao republicar.
+- **`published_data` nunca sai pela API.** Para saber o que está no ar, olhe `published_at` e
+  `published_inbox_id`.
+- **`form_data` no update SUBSTITUI o desenho inteiro.** Não há merge. Leia com `show`, altere e
+  mande o desenho completo de volta.
+- **A cópia nasce desligada e não publicada** — e copia o `inbox_id`. Imagens viram blobs novos.
+- **Publicar não ativa.** `publish` (foto) e `update` com `active: true` são dois passos.
+- **Flag desligada = página 404.** Tools funcionando + link 404 = feature `lead_forms` desligada.
+- **`media_urls` só existe no `show`.**
+- **`answers` tem chaves sintéticas** `"<node_id>::<n>"` (bloco de Ações) — não são ids de bloco.
+- **`embed_allowed` é veredito do servidor** (`check_embed`) — escrever `true` na mão faz a página
+  tentar um iframe que pode estar bloqueado.
+- **Nunca escreva segredo em cabeçalho/corpo literal** de `api_request` — use
+  `{{conta.<variável>}}`, que resolve só no servidor.
+- **Não há tool de rewind**: o "Voltar e corrigir" é da página pública (o lead corrige a própria
+  resposta; telefone corrigido reencaminha a mensagem pro número certo). Pela API de dashboard,
+  respostas são somente leitura.

package/dist/docs/resources/glossary.md

@@ -70,6 +70,10 @@ Glossário completo de termos, status codes, enums e conceitos da plataforma. Us
 - `private`: `true` = nota privada (só visível pra equipe, não pro cliente)
 - `sender_type`: `User`, `Contact`, `Captain::Assistant`, `AgentBot`
 - `processed_message_content`: texto após processamento (com markdown removido, links resolvidos)
+- `content_attributes.forwarded`: `true` = a mensagem foi ENCAMINHADA pelo cliente (nos dois canais
+  de WhatsApp — oficial e QR Code). A bolha mostra o selo "Encaminhada"
+- `content_attributes.frequently_forwarded`: `true` = encaminhada MUITAS vezes (o "encaminhada com
+  frequência" do WhatsApp). Útil pra responder "essa mensagem foi encaminhada?" sem chutar
 
 ## Attachment (Anexo)
 
@@ -93,6 +97,13 @@ Glossário completo de termos, status codes, enums e conceitos da plataforma. Us
 - `file_size`: bytes
 - `width`/`height`: pixels (imagens/vídeos)
 
+### Tipo de arquivo não reprova mais (15/08/2026)
+
+No anexo de **mensagem**, QUALQUER extensão é aceita — a validação é só de TAMANHO. Tipo sem teto
+próprio cai no teto de "documento" (o maior). O `file_type` `file` cobre tudo que não é
+imagem/áudio/vídeo. **Dois caminhos continuam com lista fechada de tipos permitidos**: o upload por
+URL (o teste de mídia do FlowBuilder) e o chat interno da equipe — não confunda os três.
+
 ## Contact (Contato)
 
 ### Campos importantes
@@ -300,6 +311,12 @@ comportamento intencional.
 - `start_time`, `end_time`: ISO 8601
 - `status`: `scheduled`, `cancelled`, `completed`
 
+**A IA agenda EXCLUSIVAMENTE por agenda de Booking (15/08/2026).** Não existe mais agendamento
+avulso/direto pela IA — ela consulta as agendas liberadas, respeita os dias em que a agenda não
+abre e só então cria a reserva. Depois de agendar, ela mesma entrega o link do Google Meet quando o
+tipo de agendamento gera Meet (o link nasce alguns segundos depois; o sistema espera e volta pra
+mandar). Detalhes em `lionchat://docs/best-practices`.
+
 ## Métricas (Reports)
 
 ### Endpoints `lionchat_reports_*` retornam métricas em SEGUNDOS por padrão
@@ -406,7 +423,7 @@ Campos MUTÁVEIS (atualizáveis livremente por IA/integração): `marital_status
 |---|---|---|---|
 | **LionCalls** | Voz pelo WhatsApp em caixa **QR Code**, mas pelo **motor próprio do LionChat** (credencial global, 1 sessão por caixa; flag `lioncalls_calling`, nasce desligada e é ligada conta a conta) | **NENHUMA — sem tool no MCP** | 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 com softphone no navegador (ramais, saldo, recarga) | `voip_*` | Telefone |
+| **VoIP (Zenvia)** | Telefonia COMUM com softphone no navegador (ramais, ligações) | `voip_*` | Telefone |
 | **VTCall** | Telefonia por **PABX click-to-call**, config por conta + ramal por atendente; **sem softphone no navegador** — o atendente fala pelo app/ramal do VTCall | `vtcall_settings_*` (show/update/test_connection), `vtcall_ramals_*` (list/create/destroy) | Telefone (PABX do cliente) |
 
 Quando o usuário falar "ligação", descubra o canal ANTES de responder: caixa QR Code → **LionCalls**;
@@ -460,3 +477,34 @@ cards daquele funil).
 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.
+
+## LeadForm (Formulário público de captação)
+
+Formulário de captura próprio da conta, com página pública (link `/forms/<conta>/<slug>`), montado
+num construtor de blocos. Feature liberada conta a conta.
+
+### `LeadFormResponse.status`
+| Valor | Significado |
+|---|---|
+| `in_progress` | O lead começou e ainda está preenchendo |
+| `completed` | Chegou ao fim do formulário |
+| `abandoned` | Parou no meio e a janela de abandono do formulário venceu |
+
+O contato nasce em TRÊS momentos (mudou em 16/08): conclusão, fechamento do abandono, ou logo
+antes de um bloco de Enviar WhatsApp. Resposta `abandoned` ganha o contato no fechamento do
+abandono — com as respostas que a pessoa deu. Enquanto preenche, a lista de respostas mostra
+`contact: {id: null, ..., pending: true}`.
+
+Termos do formulário (18/08):
+- **Caixa vinculada** — a caixa de WhatsApp do formulário (`inbox_id`); obrigatória pra publicar.
+- **Link identificado** — link de formulário enviado numa conversa sai carimbado (`lt_form`) e o
+  formulário pula nome/telefone/e-mail já conhecidos, sem nunca exibir o dado.
+- **Simulador** — `lead_forms_test_run`: roda o rascunho no motor real sem deixar rastro.
+- **Página externa (`embed`)** — bloco que exibe um site de fora dentro do formulário (checkout,
+  simulador, agenda), com conferência prévia de "aceita iframe?" (`check_embed`).
+- **Definir variável (`set_variable`)** — bloco invisível que cria `{{var.<nome>}}`.
+- **Agendamento (`booking`)** — calendário dentro do formulário, ligado a um tipo de evento.
+
+Detalhes completos (construtor, página pública, blocos, gatilhos de flow, tetos e limites) no
+resource `lionchat://docs/formularios-publicos`.
+