@lionchat/mcp-server 1.29.0 → 1.31.0

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

@@ -62,7 +62,7 @@ Todo node tem essa estrutura base:
 
 **ATENÇÃO — chave `items`, não `triggers` (corrigido 19/08/2026).** Os gatilhos vão em **`data.items`**, cada item no formato **`{ "key": "...", "config": { ...filtros... } }`**. O formato antigo (`data.triggers` + `type` + filtros soltos no topo) ainda é aceito pelo motor por compatibilidade, mas **NÃO deve ser usado em fluxo novo**: o editor do FlowBuilder lê apenas `data.items`, então um fluxo gravado no formato antigo **dispara normalmente mas abre com o bloco Início EM BRANCO no painel do cliente** — e um clique em "Concluir" naquele modal apagava o gatilho em silêncio. Foram 53 fluxos de 9 contas nesse estado até o conserto de 19/08. Alguns leitores do backend (`has_webhook_trigger?` do disparo por webhook, o filtro de Campanha de Fluxo, o gatilho LionTrack e o histórico de execução) também só entendem `items`.
 
-**Triggers válidos:** `message_received`, `message_sent`, `conversation_created`, `conversation_resolved`, `conversation_reopened`, `team_changed`, `assignee_changed`, `label_added`, `label_removed`, `sla_missed`, `card_created`, `card_moved`, `card_won`, `card_lost`, `conversation_attribute_changed`, `card_attribute_changed`, `contact_attribute_changed`, `date_trigger`, `campaign_trigger`, `manual_trigger`, `webhook_received`, `page_track`, `group_participant_joined`, `group_participant_left`, `lead_form_completed`, `lead_form_milestone`, `lead_form_abandoned`, `booking_created`, `booking_cancelled`, `booking_rescheduled`, `booking_completed`.
+**Triggers válidos:** `message_received`, `message_sent`, `conversation_created`, `conversation_resolved`, `conversation_reopened`, `team_changed`, `assignee_changed`, `label_added`, `label_removed`, `sla_missed`, `card_created`, `card_moved`, `card_won`, `card_lost`, `card_opened`, `card_snoozed`, `conversation_attribute_changed`, `card_attribute_changed`, `contact_attribute_changed`, `date_trigger`, `campaign_trigger`, `manual_trigger`, `webhook_received`, `page_track`, `group_participant_joined`, `group_participant_left`, `lead_form_completed`, `lead_form_milestone`, `lead_form_abandoned`, `booking_created`, `booking_cancelled`, `booking_rescheduled`, `booking_completed`.
 
 **NÃO existem** os gatilhos `webhook` (o correto é **`webhook_received`**) nem `cron` (para disparo por data use `date_trigger`; para disparo em lote use `campaign_trigger` + Campanha de Fluxo). Até 19/08/2026 este guia listava os dois por engano — o fluxo 180 da conta 54 ficou ATIVO com `webhook` e **nunca disparou uma vez em 26 dias**, sem erro nenhum.
 
@@ -74,6 +74,7 @@ Todo node tem essa estrutura base:
 - `label_added` / `label_removed`: `label_names` (array de slugs). NÃO use `label` (singular) — é ignorado.
 - `card_created` / `card_moved`: `funnel_ids` (array de STRINGS, ex.: `["37"]` — número puro `[37]` NÃO casa) + `funnel_stages` (array de `"funnel_id:chave_da_etapa"`, ex.: `"37:agendamento_pendente"`). A `chave_da_etapa` é a CHAVE INTERNA da etapa no funil (slug legível em funis de template; pode ser um UUID/`stage_<n>` em etapa criada à mão ou funil duplicado) — NÃO o nome exibido na tela. Sem `funnel_ids` → dispara em qualquer funil; com `funnel_ids` mas sem `funnel_stages` → qualquer etapa daquele(s) funil(is). O card precisa estar num funil listado em `funnel_ids` pra o filtro de etapa valer. ATENÇÃO: dois flows ATIVOS na mesma inbox com `card_created`/`card_moved` de funil/etapa sobrepostos são bloqueados na criação/ativação (ver `flow_trigger_conflict` no fim deste guia).
 - `team_changed`: `team_ids` (array de STRINGS; vazio = qualquer equipe). `assignee_changed`: `agent_ids` (array de STRINGS; vazio = qualquer atendente). `card_won` / `card_lost`: `funnel_ids` (array de STRINGS) — disparam SÓ quando o STATUS do card vira ganho/perdido, nunca por etapa com esse nome.
+- `card_opened` ("Card aberto") / `card_snoozed` ("Card adiado") — NOVOS 11/10/2026, mesma config `funnel_ids` (array de STRINGS; vazio = qualquer funil). `card_snoozed` dispara quando o card é ADIADO. `card_opened` dispara quando um card adiado ABRE (pela data, por alguém ou por automação) e também quando um card ganho/perdido é REABERTO — card NOVO não dispara (para isso existe `card_created`). Pela data, o fluxo sai pela fila de disparos agendados, uma vez por card. Use `{{trigger.kanban.previous_status}}` (`snoozed`/`won`/`lost`) para separar "voltou do adiamento" de "reabriram um ganho/perdido".
 - `page_track` (LionTrack, só flow individual): `{ "track_type": "visited_page"|"event_fired", "urls": [...], "operator": "contains"|"exact"|"starts_with", "event_names": [...], "event_operator": "equals"|"contains", "cooldown_hours": 24 }` — `cooldown_hours` (padrão 24, mínimo 1) não re-dispara pro mesmo contato dentro da janela.
 - `conversation_attribute_changed` / `card_attribute_changed` (novo 2026-07-08): disparam na VIRADA de um atributo (da CONVERSA ou do CARD do kanban) pro valor que casa — RE-ENTRAM toda vez que o atributo muda pro valor alvo. Config: `{ "logic": "and"|"or", "rules": [ { "attr_key": "...", "operator": "...", "value": "..." } ] }` (uma rule pode usar `values: [...]` no lugar de `value` pra multi-valor). O `attrSource` é IMPLÍCITO pela chave do gatilho (conversa vs card) — NÃO informe. Operadores (contexto REATIVO — desde 09/07 `is_empty`/`is_not_empty` NÃO valem aqui, pois "está vazio AGORA" dispararia a cada evento; use-os só no nó Condição): `equal`/`not_equal`/`contains`/`not_contains`/`starts_with`/`ends_with`/`greater_than`/`less_than`/`number_range`. Só `card_attribute_changed` aceita `funnel_id`/`card_source` opcionais dentro da rule (pra achar o card). Rule sem `attr_key` é ignorada.
 - `contact_attribute_changed` (novo 2026-07-22 — "Atributo do contato muda"): dispara quando um atributo personalizado do **CONTATO** muda e a condição casa — mesmo com o contato fora de flow. Item: `{ "key": "contact_attribute_changed", "config": { "logic": "and"|"or", "rules": [ { "attrSource": "contact", "attr_key": "...", "operator": "...", "value": "..." } ] } }` (1 a 10 rules; `values: [...]` pra multi-valor). **DIFERENTE dos irmãos de 08/07: aqui o `attrSource` VAI na rule e é SEMPRE `"contact"`.** Operadores iguais aos do nó Condição. **VERSÃO SEGURA por decisão de produto:** dispara SÓ na conversa mais recente que JÁ EXISTE numa caixa do flow (reabre se resolvida); contato sem conversa NÃO dispara e NUNCA cria conversa. Dedup de 30s por contato + anti-loop por profundidade de cadeia (flow que muda atributo que dispara flow…). Só flows de conversa.
@@ -99,6 +100,21 @@ Todo node tem essa estrutura base:
   Regras: `attr_key` é **obrigatório**. `trigger_uuid` é preenchido pelo backend no save (NÃO envie; se enviar é preservado). 29/02 em ano não-bissexto colapsa p/ 28/02. Disparo vencido tem tolerância de 24h. Se `inbox_mode` for `fixed` e a caixa for desvinculada do flow depois, os envios daquele gatilho são **pulados** (visíveis em `flows_executions_list`). Caixa oficial WhatsApp exige template na 1ª mensagem se a conversa for criada nova (senão pula). Ativar o flow agenda automaticamente os contatos que já têm a data preenchida.
   - **`attr_source: 'conversation'` (novo 2026-07-18):** a data vem de um atributo de DATA da CONVERSA (não do contato). Dispara NAQUELA conversa (reabre se resolvida). `attr_key` = chave de atributo de conversa tipo Data; o horário-por-atributo lê da conversa. NÃO tem seletor de caixa (a conversa já é conhecida) — não envie `inbox_mode`/`inbox_id`. NÃO use `repeat_yearly` (conversa é evento pontual — vetado com keep_both). SEM agendamento retroativo: só agenda o que for escrito/alterado APÓS ativar (100% forward). Ausente = `'contact'` (comportamento legado).
   - **`overwrite_mode` (novo 2026-07-18):** `'replace'` (default) = trocar a data cancela o agendamento anterior (correção de data errada não dispara em dobro). `'keep_both'` = acumula (cada data seu próprio disparo) — **SÓ com `attr_source: 'conversation'`** (vetado no contato) e **incompatível com `repeat_yearly`**. Os disparos futuros pendentes ficam visíveis/canceláveis na aba "Agendados" do editor.
+  - **QUANDO a mensagem sai de verdade (mudou em 2026-10-02):** o horário configurado passou a ser
+    **respeitado exatamente**. Até 02/10 o motor somava `id do contato % 180` **MINUTOS** ao horário
+    escolhido (espalhamento anti-banimento): quem configurava 18:00 podia receber às 20:50, e isso
+    nunca esteve documentado aqui. Caso real: Villa Eyá, 18:00 configurado, 19:50 entregue.
+    O que espaça agora é a **fila por caixa**, no momento do envio, e só quando há fila de verdade:
+    - **1 pessoa na data** → sai no horário configurado, nos dois canais.
+    - **Caixa QR Code (WAHA)**, várias pessoas na mesma data → **20 a 40 segundos entre cada**
+      (sorteado — intervalo exato é padrão de robô). 50 aniversariantes ≈ 25 min; 500 ≈ 4 h.
+      **Ao montar aniversário em massa no QR Code, avise o cliente disso** — não é atraso, é a
+      proteção que impede o número de ser bloqueado. A mesma fila atende os lembretes da e-Clínica:
+      se as duas coisas saem pela MESMA caixa, elas dividem a vaga.
+    - **Caixa oficial (Cloud)** → **10 mensagens por segundo** por número da Meta, com recuo
+      automático se a Meta reclamar (o mesmo freio da campanha). 5.000 aniversariantes ≈ 8 min.
+    - **Atraso maior que 24 h não sai**: aviso parado por queda do sistema é marcado `vencida_expirada`
+      no histórico em vez de ser entregue atrasado. O aniversário do ano seguinte continua agendado.
   - **Ver/cancelar os agendamentos (novo 2026-07-20):** `flows_scheduled_firings_list` (flow_id) lista os disparos FUTUROS pendentes do Gatilho de Data (quando vai disparar, atributo/valor que gerou, fonte contato/conversa, contato/conversa alvo). `flows_scheduled_firings_cancel` (flow_id, id) cancela um — se já disparou responde 409 `ja_disparado` e nada muda. Só flows com Gatilho de Data; ADMIN + flowbuilder_manage.
 
 **Trigger `campaign_trigger` — Gatilho "Campanha" (novo 2026-07-28):** LIBERA o flow para ser disparado
@@ -137,7 +153,7 @@ Receita completa: `flows_create`/`flows_update` com o item no start → `flows_l
 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.
 
-**Gatilhos de AGENDAMENTO — Booking NATIVO do LionChat (2026-08-20):** `booking_created` (alguém marcou pelo link público, pela IA ou pelo painel), `booking_cancelled` (paciente cancelou pelo link, IA cancelou ou a equipe cancelou na Agenda), `booking_rescheduled` (a data/hora mudou — link do paciente, IA, editar/adiar na Agenda), `booking_completed` (equipe concluiu na Agenda; exige a Agenda unificada ligada na conta). **Não é e-Clínica.** Config (tudo opcional, vazio = todos): `booking_event_type_ids` (array de ids de tipo de agendamento, **STRING**), `agent_ids` (array de ids de usuário — o RESPONSÁVEL da tarefa), `create_conversation` (boolean, padrão `false`: só dispara para quem já tem conversa numa caixa do flow; `true` = cria a conversa na 1ª caixa do flow). Exemplo: `{ "key": "booking_created", "config": { "booking_event_type_ids": ["44"], "agent_ids": [], "create_conversation": true } }`. São INERTES a evento de conversa (quem dispara é o `Booking::FlowTriggerDispatcher`, por CONTA — caixa do flow só define onde a conversa é criada/reusada). Variáveis no flow: `{{booking.date}}` (DD/MM/AAAA), `{{booking.time}}`, `{{booking.weekday}}`, `{{booking.datetime}}` (ISO), `{{booking.type}}`, `{{booking.type_format}}` (presencial/videochamada), `{{booking.duration}}`, `{{booking.agent}}`, `{{booking.status}}` (confirmado/cancelado/remarcado/concluído), `{{booking.description}}`, `{{booking.cancel_url}}`, `{{booking.reschedule_url}}`, `{{booking.color}}`, `{{booking.id}}`; só no remarcado: `{{booking.previous_date}}`, `{{booking.previous_time}}`, `{{booking.previous_datetime}}`; `{{booking.meeting_url}}` NÃO vem no criado (nasce vazio). Data/hora vêm da TAREFA da Agenda (sempre atuais). Regras: o evento mais novo SUBSTITUI a rodada ativa do mesmo flow na mesma conversa (2ª consulta do mesmo paciente, ou cancelado chegando com o criado ainda esperando resposta); excluir a tarefa, reabrir cancelada ou desfazer conclusão NÃO disparam; adiar (snooze) conta como remarcado; tipo com confirmação/lembrete próprios ligados + `booking_created` = o paciente pode receber duas mensagens (a tela avisa). Colisão entre flows é por CONTA: mesmo kind + tipos se cruzando + agentes se cruzando (vazio = todos). Há também `{{booking.event}}` (`created`|`cancelled`|`rescheduled`|`completed` — bom pra condição; não aparece no seletor da tela, mas resolve); `{{trigger.type}}` = a chave do gatilho (ex.: `booking_created`), `{{trigger.kind}}` = `created`|`cancelled`|`rescheduled`|`completed` e `{{trigger.booking_id}}`. SÓ flow de conversa **individual** (a tela nem oferece em flow de grupo); **nunca dispara flow `ai_tool`**. Em caixa WhatsApp OFICIAL, conversa criada nova (ou parada há mais de 24h) está FORA da janela — texto livre no 1º bloco cai em `window_closed`/erro; comece por template.
+**Gatilhos de AGENDAMENTO — Booking NATIVO do LionChat (2026-08-20):** `booking_created` (alguém marcou pelo link público, pela IA ou pelo painel), `booking_cancelled` (paciente cancelou pelo link, IA cancelou ou a equipe cancelou na Agenda), `booking_rescheduled` (a data/hora mudou — link do paciente, IA, editar/adiar na Agenda), `booking_completed` (equipe concluiu na Agenda; exige a Agenda unificada ligada na conta). **Não é e-Clínica.** Config (tudo opcional, vazio = todos): `booking_event_type_ids` (array de ids de tipo de agendamento, **STRING**), `agent_ids` (array de ids de usuário — o RESPONSÁVEL da tarefa), `create_conversation` (boolean, padrão `false`: só dispara para quem já tem conversa numa caixa do flow; `true` = cria a conversa na 1ª caixa do flow). Exemplo: `{ "key": "booking_created", "config": { "booking_event_type_ids": ["44"], "agent_ids": [], "create_conversation": true } }`. São INERTES a evento de conversa (quem dispara é o `Booking::FlowTriggerDispatcher`, por CONTA — caixa do flow só define onde a conversa é criada/reusada). Variáveis no flow: `{{booking.date}}` (DD/MM/AAAA), `{{booking.time}}`, `{{booking.weekday}}`, `{{booking.datetime}}` (ISO), `{{booking.type}}`, `{{booking.type_format}}` (presencial/videochamada), `{{booking.duration}}`, `{{booking.agent}}`, `{{booking.status}}` (confirmado/cancelado/remarcado/concluído), `{{booking.description}}`, `{{booking.cancel_url}}`, `{{booking.reschedule_url}}`, `{{booking.confirm_url}}`, `{{booking.calendar_url}}` (16/10: página onde o cliente salva o compromisso na agenda DELE, sem e-mail; no remarcado já sai com a hora nova — é o jeito de avisar a mudança, pedindo para apagar o compromisso antigo), `{{booking.color}}`, `{{booking.id}}`; só no remarcado: `{{booking.previous_date}}`, `{{booking.previous_time}}`, `{{booking.previous_datetime}}`; `{{booking.meeting_url}}` NÃO vem no criado (nasce vazio). Data/hora vêm da TAREFA da Agenda (sempre atuais). Regras: o evento mais novo SUBSTITUI a rodada ativa do mesmo flow na mesma conversa (2ª consulta do mesmo paciente, ou cancelado chegando com o criado ainda esperando resposta); excluir a tarefa, reabrir cancelada ou desfazer conclusão NÃO disparam; adiar (snooze) conta como remarcado; tipo com confirmação/lembrete próprios ligados + `booking_created` = o paciente pode receber duas mensagens (a tela avisa). Colisão entre flows é por CONTA: mesmo kind + tipos se cruzando + agentes se cruzando (vazio = todos). Há também `{{booking.event}}` (`created`|`cancelled`|`rescheduled`|`completed` — bom pra condição; não aparece no seletor da tela, mas resolve); `{{trigger.type}}` = a chave do gatilho (ex.: `booking_created`), `{{trigger.kind}}` = `created`|`cancelled`|`rescheduled`|`completed` e `{{trigger.booking_id}}`. SÓ flow de conversa **individual** (a tela nem oferece em flow de grupo); **nunca dispara flow `ai_tool`**. Em caixa WhatsApp OFICIAL, conversa criada nova (ou parada há mais de 24h) está FORA da janela — texto livre no 1º bloco cai em `window_closed`/erro; comece por template.
 
 **TRAVA DE GATILHO DUPLICADO (2026-06-16) — leia ANTES de ativar/criar flow ativo:** o sistema BLOQUEIA ter dois flows ATIVOS com o MESMO gatilho na MESMA inbox e mesmo `conversation_mode` (evita o evento disparar dois flows). Colisão = mesmo tipo de gatilho + config cruzando (mesmas keywords/funil/labels/url/etc) + inbox compartilhada + mesmo modo. EXCEÇÕES que podem coexistir: `webhook_received`, `manual_trigger` e `campaign_trigger` (este último porque não dispara por evento — é só uma autorização para a campanha).
 - **`date_trigger` separa por HORÁRIO (24/09/2026):** dois flows no mesmo campo de data, mesma direção e mesmos dias NÃO colidem se os dois tiverem horário FIXO diferente (ex.: "1 dia depois às 08:00" e "às 14:00"). Horário vindo de atributo/fórmula continua colidindo (só existe na hora do disparo); `send_time` vazio conta como 09:00 e "8:00" = "08:00". A entrega é de 10 em 10 minutos — horários a menos de 10 min podem sair juntos.
@@ -382,6 +398,7 @@ só pra destravar, ela pode sair.
 | `conversation_has_ai_agent` / `conversation_no_ai_agent` / `conversation_not_ai_agent` | agente de IA atribuído (novo 2026-08-01) — ver abaixo |
 | `contact_has_label` / `contact_no_label` / `conversation_has_label` / `conversation_no_label` | labels |
 | `kanban_exists` / `kanban_in_stage` / `kanban_won` / `kanban_lost` | card no funil. `funnel_id` é CHAVE SEPARADA da condição (número, ex.: `"funnel_id": 37`). A etapa vai em `value` (slug puro da etapa, ex.: `"avaliacao_aceita"`) ou em `stage` — NÃO no formato `"37:etapa"`. Ex.: `{ "operator": "kanban_in_stage", "funnel_id": 37, "value": "avaliacao_aceita" }` |
+| `kanban_snoozed` (11/10/2026) | card ADIADO no funil — `field: '_kanban_status'`, `funnel_id` separado, igual às irmãs `kanban_won`/`kanban_lost` (mesma regra do card que iniciou o fluxo). Não existe condição "card aberto" |
 | `card_attr_equals` / `card_attr_contains` | atributo do card (`attrSource: 'card'` + `attr_key`; aceita `card_source: 'trigger'` p/ ler o card que iniciou o flow) |
 | `pagetrack_visited` / `pagetrack_event` | LionTrack |
 | `sla_check` | status do SLA da conversa (usa `value` = código fixo; ver abaixo) |
@@ -442,7 +459,7 @@ campanha"):
   `origin_first_kind`/`origin_first_platform`, `origin_last_kind`/`origin_last_platform`, `origin_*` em geral
   (origem unificada), `ctwa_*` (anúncio click-to-WhatsApp: `ctwa_ad_id`, `ctwa_ad_title`, `ctwa_campaign_name`,
   `ctwa_adset_name`...), `meta_lead_*` (formulário Meta Lead Ads), `lt_*` (LionTrack: UTMs, página, dispositivo).
-  Veja a lista real com `lionchat_custom_attributes_list` (`attribute_model: conversation`, `include_system: true` — as chaves de campanha são atributos de sistema).
+  Veja a lista real com `lionchat_custom_attributes_list` (`attribute_model: conversation_attribute` — com o sufixo; só `conversation` devolve a lista VAZIA —, `include_system: true` — as chaves de campanha são atributos de sistema).
 - **Valores fechados** de `origin_kind` (e `origin_first_kind`/`origin_last_kind`): `paid_ad` (Anúncio),
   `lead_form` (Formulário), `organic` (Orgânico), `direct` (Direto), `referral` (Indicação), `manual` (Origem
   cadastrada). O painel mostra o rótulo em português, mas a comparação é pelo VALOR — `"Anúncio"` nunca casa.
@@ -543,6 +560,7 @@ o botão "Usar variável" ao lado do campo alterna lista fixa ↔ variável.
 | `set_kanban_item_status` | `{ status: 'won' \| 'lost' \| 'active' }` | Marca status do card |
 | `set_won` | `{}` | Atalho pra ganho |
 | `set_lost` | `{ reason? }` | Atalho pra perdido |
+| `snooze_kanban_item` (11/10/2026) | `{ funnel_id, amount, unit: 'hours' \| 'days', card_source? }` | "Adiar card": ADIA o card por N horas ou dias a partir da execução (`amount` inteiro, 1 ou mais; mínimo 1 hora). Só card aberto; adiar de novo troca a data. `card_source: 'trigger'` mira o card que iniciou o fluxo (aí `funnel_id` não é exigido). Diferente das irmãs de card: card ganho/perdido, sem card ou fluxo que NÃO veio de card com `card_source: 'trigger'` = ERRO visível no passo, nunca pulado. `set_open` (e `set_kanban_item_status` com `open`) num card ADIADO abre o card na hora e dispara "Card aberto". Ver "Card adiado" no kanban-deep-dive |
 | `assign_agent_card` | `{ agent_id, mode? }` | Responsável do card. `mode`: `'add'` (default — SOMA na lista), `'replace'` (só o escolhido fica; atribui antes de remover os demais) ou `'remove_all'` (tira TODOS os responsáveis; `agent_id` dispensado) |
 | `add_card_note` | `{ text }` | Nota no card. **A chave é `text`**, igual à irmã `add_private_note`. Aqui é mais grave: o motor lê SÓ `text`, sem rede — nota criada com `content` sairia REALMENTE vazia, não só invisível no formulário. Corrigido em 04/09 (a linha dizia `content`); a gravação normaliza `content` para `text` |
 | `add_card_checklist` | `{ template_id, funnel_id?, card_source? }` | Aplica um MODELO de checklist ao card (vira um grupo). `template_id` de `kanban_config.checklist_templates`. Um modelo por bloco (repita o bloco pra mais de um) |
@@ -558,7 +576,7 @@ o botão "Usar variável" ao lado do campo alterna lista fixa ↔ variável.
 
 **Handles que SAEM:** `success`. Não tem handle `error` — falhas viram warning silencioso e o flow continua.
 
-**`card_source` (blocos de card) — opcional:** as ações de card aceitam `card_source`: `'funnel'` (default — procura o card pelo `funnel_id`) ou `'trigger'` (usa o card que DISPAROU o flow, em flows iniciados por `card_created`/`card_moved`/`card_won`/`card_lost`). Com `'trigger'`, `funnel_id` deixa de ser obrigatório — EXCETO em `move_kanban_stage`/`create_kanban_item`, cujo funil/etapa são o DESTINO. Sem card-gatilho disponível, a ação é pulada (não cai no fallback de funil). Aplica-se a `move_kanban_stage`, `set_won`/`set_lost`/`set_open`, `assign_agent_card`, `add_card_note`, `add_card_checklist`, `add_card_offer`, `update_attribute` (com `attr_source: 'card'`) e às condições `card_attr_equals`/`card_attr_contains` (gravando `card_source` na própria regra).
+**`card_source` (blocos de card) — opcional:** as ações de card aceitam `card_source`: `'funnel'` (default — procura o card pelo `funnel_id`) ou `'trigger'` (usa o card que DISPAROU o flow, em flows iniciados por `card_created`/`card_moved`/`card_won`/`card_lost`/`card_opened`/`card_snoozed`). Com `'trigger'`, `funnel_id` deixa de ser obrigatório — EXCETO em `move_kanban_stage`/`create_kanban_item`, cujo funil/etapa são o DESTINO. Sem card-gatilho disponível, a ação é pulada (não cai no fallback de funil). Aplica-se a `move_kanban_stage`, `set_won`/`set_lost`/`set_open`, `snooze_kanban_item` (esta, sem card-gatilho, dá ERRO em vez de pular), `assign_agent_card`, `add_card_note`, `add_card_checklist`, `add_card_offer`, `update_attribute` (com `attr_source: 'card'`) e às condições `card_attr_equals`/`card_attr_contains` (gravando `card_source` na própria regra).
 
 **`send_conversion` — Enviar conversão (2026-09-01):**
 
@@ -608,6 +626,12 @@ o botão "Usar variável" ao lado do campo alterna lista fixa ↔ variável.
 
 **Empresa e Cargo (2026-09-25):** `contact.company_name` e `contact.job_title` valem em CONDIÇÃO (`attr_source: 'contact'`, `attr_key` igual ao path), em filtro de regras e como variável (`{{contact.company_name}}`, `{{contact.job_title}}`). São SÓ LEITURA: a ação "Alterar atributo do contato" NÃO grava esses dois (o texto Empresa anda junto com a empresa vinculada — para ligar a empresa use `lionchat_contacts_update` com `company_id`).
 
+**Empresa do contato (2026-10-16):** a empresa ligada ao contato da conversa (no máximo UMA por contato) vale como VARIÁVEL e como CONDIÇÃO, só com o módulo Empresas ligado.
+- Variável em qualquer bloco de mensagem: `{{contact.company.name}}`, `{{contact.company.legal_name}}`, `{{contact.company.cnpj}}`, `{{contact.company.phone}}`, `{{contact.company.email}}`, `{{contact.company.address.city}}`, `{{contact.company.address.state}}` e `{{contact.company.custom_attribute.<chave>}}` (campo personalizado da empresa). Contato sem empresa = vazio. Data do campo personalizado: DD/MM/AAAA no bloco de mensagem; crua (AAAA-MM-DD) em API, Definir variável e Condição — igual ao atributo do contato.
+- Condição (bloco Condição, aba Atributos, card "Atributo da empresa"): `{ "valueType": "attr_config", "attrSource": "company", "attr_key": "segmento", "operator": "equal", "value": "", "values": ["Varejo"] }`. `attr_key` = chave do campo personalizado OU cadastro com prefixo `company.name`, `company.legal_name`, `company.cnpj` (comparado só pelos dígitos), `company.phone`, `company.email`, `company.address.city`, `company.address.state`. Contato sem empresa = valor vazio (`not_equal`/`is_empty` casam). Módulo Empresas DESLIGADO = a regra NUNCA casa, nem a negativa.
+- `attrSource` fora de `contact`/`conversation`/`card`/`company` NÃO casa (antes comparava a última mensagem do cliente) e marca o bloco com aviso.
+- NÃO vale em condição de SAÍDA (`exit_conditions`), gatilho de entrada, parâmetro de ferramenta de IA nem em `update_attribute` (a ação não grava na empresa).
+
 **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.
@@ -944,6 +968,24 @@ erro). Número de celular BR escrito sem o 9 é corrigido pelo WhatsApp antes de
 sessão do canal, orçamento 8 s). Antes de 21/08 o passo dava SUCESSO mesmo com o lead fora do grupo. A
 mesma correção do 9º dígito vale no `add_participants`.
 
+**Quem volta só com o código interno (2026-10-09):** o WhatsApp devolve a pessoa RECÉM-COLOCADA só com o
+código interno dela (`<código>@lid`, sem telefone) — e horas depois continua assim. Até 09/10 o bloco comparava
+só telefone: `add_participants` acusava `nobody_changed`/`not_added` com a pessoa DENTRO do grupo (o fluxo
+parava), `create` dava `partial` falso (e mandava convite para quem já estava) e `remove_participants` dava
+SUCESSO falso. Desde 09/10 o bloco confere pelo telefone e, só para quem não casou, pergunta ao WhatsApp o
+código daquele telefone. Sem resposta do WhatsApp = conta como NÃO colocado (nunca inventa que entrou). Limite
+conhecido: número que não passou pela conferência de existência (fora do Brasil) e volte só com o código
+continua contando como fora.
+
+**De onde veio cada número (2026-10-09):** nas operações com `groupParticipants`, o passo do bloco no
+HISTÓRICO da execução (não a variável `{{grupo.*}}`) traz `participant_sources` — um item por número com
+`number`, `source` (a LINHA do campo de participantes de onde ele saiu), `typed` (`true` = digitado, sem
+variável), `informed` (o número como foi escrito, quando o WhatsApp usa outra forma) e, quando a linha é UM
+atributo personalizado sozinho (`{{conversation.custom_attribute.x}}` / `{{contact.custom_attribute.x}}`),
+`filled_by`/`filled_at` (quem preencheu aquele atributo e quando). É só anotação: nunca muda quem vai no
+pedido; origem e autor podem faltar, mas nunca saem errados. Use para responder "de onde saiu esse número?"
+em vez de concluir que o número "não está configurado".
+
 **Convite no privado de quem ficou de fora (opcional, nasce desligado; só `create`/`add_participants`;
 2026-08-21 — entra com o próximo deploy do app depois de 21/08/2026):** `groupInviteOnFailure: true` +
 `groupInviteMessage` (texto OBRIGATÓRIO nesse modo — sem texto = `invite_status: 'sem_mensagem'` e nada
@@ -1049,6 +1091,31 @@ de conexão e viram bola de neve visual. Ao gerar `position`:
 
 ---
 
+### 2.15 `ai_call` — "Ligar com IA" (17/10/2026)
+
+So em conta com `ai_calling` + `lioncalls_calling`. A IA liga para o **telefone do contato** da conversa do flow
+pela linha de ligacao do WhatsApp (LionCalls).
+
+```json
+{ "id": "ligar", "type": "ai_call", "position": {"x": 600, "y": 0},
+  "data": { "aiCallAgentId": 4, "aiCallInboxId": 82 } }
+```
+
+- `aiCallAgentId`: id de `lionchat_captain_call_agents_list`. O que a IA fala, a voz e o **tempo maximo** da ligacao
+  vem do agente (`max_duration_seconds`, 30-600 s; no tempo o motor desliga sozinho).
+- `aiCallInboxId`: id de `meta.dial_inboxes` da mesma lista (caixa com a ligacao ligada).
+- Saidas: `answered` (atendeu), `no_answer` (nao atendeu/recusou), `error` (nao deu pra ligar; motivo no historico).
+  `answered`/`no_answer` sem edge = o flow termina; `error` sem edge = execucao "Falhou".
+- Liga **uma vez**. Para insistir, outro `ai_call` depois de `no_answer` (com um `wait` no meio). **Nunca** ligue
+  `error` direto em outro `ai_call`.
+- Nao confere horario (use `condition` antes). Linha ocupada: espera a vez por ate 2 h (a IA sempre deixa uma vaga
+  para a equipe).
+- **Proibido** em flow `action`, em flow de grupo e em `ai_tool` (o save recusa). Id de outra conta tambem e recusado.
+
+**Receita — a IA de atendimento pede a ligacao:** etiqueta `ligar`; o cenario manda por a etiqueta quando o cliente
+pede para falar por telefone; flow `conversation` com gatilho `label_added` (`label_names: ["ligar"]`) -> action
+`remove_conversation_label` (`labels: ["ligar"]`) logo depois do start -> `ai_call`.
+
 ## 2-B. Três tipos de flow: `conversation`, `ai_tool` e `action`
 
 O campo `flow_type` (definido na criação, IMUTÁVEL depois) decide a natureza do flow:
@@ -1165,7 +1232,7 @@ Sempre presente:
 
 | Variável | Conteúdo |
 |---|---|
-| `{{trigger.type}}` | código do **EVENTO** que disparou — **NÃO é a chave do item do Início**. Valores reais: `message_created` (gatilho `message_received`), `message_sent`, `conversation_created`, `conversation_opened` (gatilho `conversation_reopened`), `conversation_resolved`, `label_added`, `label_removed`, `team_changed`, `assignee_changed`, `sla_missed`, `kanban_item_created`/`card_created`, `kanban_item_stage_changed`/`card_moved`, `card_status_changed` (`card_won` e `card_lost` — olhe `trigger.kind` ou o status do card), `conversation_attributes_changed`, `card_attributes_changed`, `contact_attribute_changed`, `group_participant_joined`/`_left`, `webhook_received`, `date_trigger`, `manual` (sidebar), `kanban_manual` (botão do card), `campaign` (Campanha de Fluxo), `page_track`, `activated_by_flow` (fluxo chamou fluxo), `lead_form` (os 3 gatilhos de formulário — `trigger.kind` diz `completed`/`milestone`/`abandoned`), `booking_created`/`booking_cancelled`/`booking_rescheduled`/`booking_completed`. Compare SEMPRE com esses códigos numa condição |
+| `{{trigger.type}}` | código do **EVENTO** que disparou — **NÃO é a chave do item do Início**. Valores reais: `message_created` (gatilho `message_received`), `message_sent`, `conversation_created`, `conversation_opened` (gatilho `conversation_reopened`), `conversation_resolved`, `label_added`, `label_removed`, `team_changed`, `assignee_changed`, `sla_missed`, `kanban_item_created`/`card_created`, `kanban_item_stage_changed`/`card_moved`, `card_status_changed` (`card_won`, `card_lost`, `card_opened` e `card_snoozed` — olhe `{{trigger.kanban.status}}`: `won`/`lost`/`open`/`snoozed`; rótulo "Situação do card mudou" desde 11/10/2026), `conversation_attributes_changed`, `card_attributes_changed`, `contact_attribute_changed`, `group_participant_joined`/`_left`, `webhook_received`, `date_trigger`, `manual` (sidebar), `kanban_manual` (botão do card), `campaign` (Campanha de Fluxo), `page_track`, `activated_by_flow` (fluxo chamou fluxo), `lead_form` (os 3 gatilhos de formulário — `trigger.kind` diz `completed`/`milestone`/`abandoned`), `booking_created`/`booking_cancelled`/`booking_rescheduled`/`booking_completed`. Compare SEMPRE com esses códigos numa condição |
 | `{{trigger.name}}` | rótulo legível do MESMO evento ("Mensagem recebida", "Card mudou de etapa") — use este pra ESCREVER pro cliente, e o `type` pra COMPARAR em condição |
 | `{{trigger.activated_at}}` | quando disparou (ISO 8601). Desde 20/08/2026 `name` e `activated_at` são preenchidos em TODOS os caminhos de disparo (antes só no de evento de conversa) |
 | `{{trigger.kanban_item_id}}` / `{{trigger.funnel_id}}` | só quando veio do Kanban |
@@ -1205,9 +1272,10 @@ Oferecidos no autocompletar (só quando o bloco Início tem o gatilho que os pre
 
 | Gatilhos do Início | Variáveis |
 |---|---|
-| `card_created`, `card_moved`, `card_won`, `card_lost`, `card_attribute_changed` | `{{trigger.kanban.title}}`, `{{trigger.kanban.funnel_name}}`, `{{trigger.kanban.stage_name}}`, `{{trigger.kanban.stage}}` (código da etapa) |
+| `card_created`, `card_moved`, `card_won`, `card_lost`, `card_opened`, `card_snoozed`, `card_attribute_changed` | `{{trigger.kanban.title}}`, `{{trigger.kanban.funnel_name}}`, `{{trigger.kanban.stage_name}}`, `{{trigger.kanban.stage}}` (código da etapa) |
 | `card_moved` | `{{trigger.kanban.previous_stage_name}}`, `{{trigger.kanban.previous_stage}}` |
-| `card_won`, `card_lost` | `{{trigger.kanban.status}}` (`won`/`lost`) |
+| `card_won`, `card_lost`, `card_opened`, `card_snoozed` | `{{trigger.kanban.status}}` (`won`/`lost`/`open`/`snoozed`) |
+| `card_opened` | `{{trigger.kanban.previous_status}}` (`snoozed` = voltou do adiamento; `won`/`lost` = reabriram um ganho/perdido) |
 | `label_added`, `label_removed` | `{{trigger.label.name}}` |
 | `assignee_changed` | `{{trigger.assignee.name}}` (vazio = responsável removido) |
 | `team_changed` | `{{trigger.team.name}}` (vazio = equipe removida) |
@@ -1220,7 +1288,7 @@ Resolvem mas NÃO aparecem no seletor (produtor único — só o gatilho daquela
 `{{trigger.eclinica.event|unit|date|time|compromisso|idagenda}}`, `{{trigger.lead.form|page|ad|adset|campaign|platform}}`
 (nome do anúncio, não dado de pessoa), `{{trigger.dtmf.key|campaign}}`, `{{trigger.reminder.date|time|compromisso|unit|days_before}}`,
 além de `{{trigger.kanban.id}}`/`funnel_id` (use `{{trigger.kanban_item_id}}`/`{{trigger.funnel_id}}`),
-`{{trigger.assignee.id}}`, `{{trigger.team.id}}`, `{{trigger.kanban.previous_status}}` e
+`{{trigger.assignee.id}}`, `{{trigger.team.id}}` (`{{trigger.kanban.previous_status}}` passou a ser oferecida no `card_opened`, 11/10/2026) e
 `{{trigger.group.participants_count}}`. As RESPOSTAS do lead do Meta não viram variável (só aparecem no
 histórico). Sessões anteriores a 22/08 não têm fatos gravados: essas variáveis saem vazias nelas.
 O bloco do card chama-se `kanban` — nunca `card`. Se o cliente precisar de um dado que não está aqui,
@@ -1265,7 +1333,7 @@ texto trocava o protocolo pelo id interno do banco.
     { "attr_key": "status", "attrSource": "conversation", "operator": "equal", "value": "cancelado" }
   ] }
 ```
-- `attrSource` (`'contact'`|`'conversation'`|`'card'`) VAI na rule (ao contrário do gatilho de entrada por atributo, onde é implícito).
+- `attrSource` (`'contact'`|`'conversation'`|`'card'`) VAI na rule (ao contrário do gatilho de entrada por atributo, onde é implícito). `'company'` NÃO vale aqui (só no bloco Condição): a regra de saída não lê a empresa.
 - `operator` (contexto REATIVO — desde 09/07 SEM `is_empty`/`is_not_empty`, que dispararia a cada evento; use-os só no nó Condição): `equal`/`not_equal`/`contains`/`not_contains`/`starts_with`/`ends_with`/`greater_than`/`less_than`/`number_range`. Multi-valor via `values: [...]` no lugar de `value`.
 - Reativa (09/07): só é reavaliada quando o atributo VIGIADO daquela rule realmente muda — não a cada mensagem. Cada rule exige `attr_key` + (`value` ou `values`); rule sem isso é ignorada.
 - `card` aceita `funnel_id`/`card_source` opcionais na rule.

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

@@ -549,6 +549,23 @@
 
 **Lembretes:** `attr_key` é obrigatório; `_date_of_birth` é o Aniversário nativo. `trigger_uuid` é preenchido pelo backend (não envie). Ativar o flow já agenda os contatos que têm a data. Pulos (contato sem telefone, caixa desvinculada, etc.) aparecem em `flows_executions_list`.
 
+**Quanto tempo leva, com muita gente na mesma data (mudou em 2026-10-02):** o horário configurado é
+respeitado — a primeira mensagem sai às 09:00 em ponto. As demais saem no ritmo da caixa, que existe
+para o número não ser bloqueado:
+
+| Caixa | Ritmo | 50 pessoas | 500 pessoas |
+|---|---|---|---|
+| QR Code (WAHA) | 20-40 s entre cada | ~25 min | ~4 h |
+| Oficial (Cloud) | 10 por segundo | 5 s | ~50 s |
+
+**Ao montar aniversário para uma base grande em QR Code, diga isso ao cliente antes** — ele vai ver as
+mensagens pingando e achar que travou. Não é atraso: é a trava anti-banimento. Se precisar sair rápido
+em volume, o caminho é caixa oficial ou Campanha de Fluxo (que tem agendamento por dias).
+
+Até 02/10/2026 o motor somava `id do contato % 180` MINUTOS ao horário escolhido — 18:00 podia virar
+20:50, sem nada na tela explicando. Isso acabou; se encontrar documentação antiga dizendo que o
+Gatilho de Data "espalha em até 3 horas", está desatualizada.
+
 ---
 
 ## 17. Gestão de Grupos WhatsApp por fluxo (`update_group`)

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

@@ -35,6 +35,7 @@ caixa de WhatsApp vinculada e (opcionalmente) dispara um fluxo do FlowBuilder no
 | **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 |
+| **Formulário do WhatsApp** (17/10/2026) | Formulário nativo da Meta, preenchido DENTRO do WhatsApp, aberto por botão de modelo de mensagem. Ferramentas `lionchat_whatsapp_forms_*` — seção própria no fim deste documento |
 
 ## Ferramentas disponíveis
 
@@ -608,3 +609,141 @@ agendar (com `required: true` essa saída deixa de existir). O tipo de evento ve
   blocos. Teste o trecho seguinte pela página pública.
 - **`stats.views` é de vida inteira** (ignora `days`); `stats.milestones` não vê marco em `items`.
 - **`name` é interno; `settings.public_title` é o que o lead vê** (vazio = cai no `name`).
+
+## Formulário do WhatsApp (WhatsApp Flows da Meta) — 17/10/2026
+
+Segundo tipo da área Formulários. É o formulário **nativo do WhatsApp**: o cliente toca num botão de um modelo de
+mensagem e preenche sem sair do WhatsApp; as respostas voltam para a conversa ("Formulário respondido", pergunta por
+pergunta). Só caixa do **WhatsApp Oficial** (Cloud API). Montar, publicar, aposentar e excluir = só administrador;
+listar e ver = qualquer pessoa da conta. Não confundir com o **Formulário público** (o resto deste documento, página
+com link próprio) nem com o formulário de anúncio da Meta (MetaLeadForm).
+
+### Ferramentas
+
+| Ferramenta | Para quê |
+|---|---|
+| `lionchat_whatsapp_forms_list` | Lista (`inbox_id` filtra pela conta do WhatsApp; `with_questions=true` traz `questions: [{code, label}]`; `refresh=true` relê o estado na Meta) |
+| `lionchat_whatsapp_forms_show` | Rascunho completo, `save_targets`, `image_urls`, `limits` (os limites da Meta, por tipo), `published_version`, `version_outdated` |
+| `lionchat_whatsapp_forms_create` | Cria rascunho `{name, inbox_id, editor_data?}` — nada vai para a Meta ainda |
+| `lionchat_whatsapp_forms_update` | Salva `name`, `editor_data` (SUBSTITUI o rascunho inteiro) e/ou `save_targets` |
+| `lionchat_whatsapp_forms_images` | Sobe imagem POR LINK (`url` http/https de imagem pública): o servidor baixa, reduz para o limite da Meta e devolve `{blob_id, url, width, height}` |
+| `lionchat_whatsapp_forms_publish` | Gera o arquivo, cria/edita na Meta e publica |
+| `lionchat_whatsapp_forms_preview` | Endereço da prévia oficial da Meta (abre sem login, 30 dias) |
+| `lionchat_whatsapp_forms_deprecate` | Aposenta na Meta — IRREVERSÍVEL |
+| `lionchat_whatsapp_forms_destroy` | Exclui rascunho ou aposentado |
+
+### Passo a passo
+1. `_create` com `name` (único na conta do WhatsApp — a Meta recusa nome repetido ao publicar) e `inbox_id` de uma
+   caixa oficial da conta (outra caixa = 422 `inbox_must_be_official`).
+2. Imagem (se houver): `_images` com o link → use o `blob_id` em `{ "type": "image", "image": "<blob_id>" }`.
+3. `_update` com o `editor_data` completo (leia com `_show` antes de editar: o rascunho é substituído inteiro).
+4. `_publish`. Fica PARA SEMPRE na conta do WhatsApp do cliente (só dá para aposentar). Republicar depois de editar
+   mantém os modelos funcionando, sem nova aprovação.
+5. Botão no modelo: `lionchat_inboxes_whatsapp_templates_create` com
+   `{type: 'BUTTONS', buttons: [{type: 'FLOW', text: 'Preencher', flow_id: '<meta_flow_id>', flow_action: 'navigate'}]}`
+   (`meta_flow_id` vem do `_list`/`_show`; o formulário tem de estar publicado; no máximo 1 botão FLOW por modelo; texto
+   do botão até 25). A Meta costuma aprovar em minutos e pode trocar a categoria para Marketing. Trocar o formulário do
+   botão de um modelo aprovado manda o modelo de volta para análise.
+6. Envie o modelo como qualquer outro (conversa, campanha, fluxo, automação). O componente que a Meta exige para o
+   botão de formulário é montado pelo servidor — não mande nada a mais.
+7. (Opcional) Fluxo com gatilho `whatsapp_form_answered` — config `{whatsapp_form_id: '<id nosso, STRING>'}` (vazio =
+   qualquer formulário; lista também é aceita). Variáveis `{{trigger.form.name}}`, `{{trigger.form.id}}`,
+   `{{trigger.form.f_<n>}}` (a resposta de cada pergunta já em texto).
+
+### O `editor_data`
+```json
+{ "category": "SURVEY", "next_label": "Continuar", "submit_label": "Enviar",
+  "screens": [
+    { "title": "Seus dados",
+      "fields": [
+        { "type": "heading", "text": "Conte um pouco sobre você" },
+        { "type": "image", "image": "123", "alt_text": "Logo da clínica" },
+        { "type": "short_text", "label": "Seu nome", "required": true, "max_chars": 60 },
+        { "type": "single_choice", "label": "Como nos achou?",
+          "options": [{ "label": "Instagram" }, { "label": "Indicação", "description": "Amigo ou parente" }] },
+        { "type": "calendar", "label": "Entrada", "mode": "range", "end_label": "Saída", "days": ["Fri", "Sat"] },
+        { "type": "photo", "label": "Foto do documento", "max_files": 2 },
+        { "type": "link", "text": "Nossos termos", "url": "https://exemplo.com/termos" }
+      ] } ] }
+```
+- `category`: SIGN_UP, SIGN_IN, APPOINTMENT_BOOKING, LEAD_GENERATION, CONTACT_US, CUSTOMER_SUPPORT, SURVEY, OTHER.
+- `next_label` (botão das telas do meio) e `submit_label` (botão da última tela, que envia): até 35 caracteres.
+  Só a ÚLTIMA tela envia; as anteriores levam para a seguinte.
+- Campo NOVO vai sem `code`: o servidor dá `f_<n>` (opções `o_<n>`). Código já publicado NUNCA é reaproveitado.
+- Perguntas (limite do texto da pergunta entre parênteses — use `helper`, até 80, para explicar mais):
+  `short_text`, `email`, `phone`, `number`, `long_text` (20); `date` e `calendar` (40); `single_choice` (30; até 200
+  opções, passou de 20 vira lista suspensa) e `multiple_choice` (30; até 20 opções); opção até 30, descrição da opção
+  até 300; `opt_in` (aceite, 120; `read_more_url` mostra um "Ler mais" que abre o link); `photo` e `document` (80;
+  `description` até 300, `max_files` 1-10, `max_size_mb` 1-25 — a foto sai SEMPRE com no máximo 5 MB, o limite de
+  recebimento do WhatsApp oficial; foto: `source` camera_gallery|camera|gallery; arquivo: `file_kinds`
+  pdf|word|spreadsheet|presentation|image|text|compressed|video). `required: true` = obrigatória (na foto/arquivo
+  vira "pelo menos 1").
+- Ajustes: `max_chars` (NÚMERO 1-4000), `min_date`/`max_date` "AAAA-MM-DD" (data fixa — não existe "a partir de
+  hoje"), calendário `mode` single|range + `end_label`/`end_helper` (rótulo e ajuda do fim; a ajuda vai nas DUAS
+  pontas ou em nenhuma) + `title` (80) + `description` (300) + `days` (Mon..Sun, os dias que podem ser escolhidos);
+  escolha múltipla `min_selected`/`max_selected` (nunca acima do número de opções, mínimo nunca acima do máximo).
+- Conteúdo (`text`): `heading` e `subheading` (80), `paragraph` e `caption` (4096), `link` (`text` até 25 + `url`
+  http/https), `image` (`image` = `blob_id` do `_images`, `alt_text` até 100).
+- Tetos: 10 telas; 40 campos e 5 aceites por tela; título de tela 30; por tela 1 foto/arquivo, 3 imagens e 2 links;
+  até 10 arquivos no formulário inteiro (soma do `max_files`).
+
+### Salvar x publicar (onde cada erro aparece)
+- **Salvar** (`_create`/`_update`) recusa com 422 `{errors: [...]}` só o FORMATO: tipo desconhecido, número fora da
+  faixa, data fora do formato, lista com valor desconhecido, `category` fora da lista, telas fora de 1-10, mais de 40
+  campos ou 5 aceites numa tela, opções em formato errado. Limite de caracteres da Meta NÃO barra o salvar
+  (dá para salvar no meio do caminho).
+- **Publicar** recusa com 422 `{problems: [{code, screen, field, limit}], error, form}` (`screen`/`field` começam em
+  0). Códigos de `problems`:
+
+| code | O que corrigir |
+|---|---|
+| `no_questions` | o formulário não tem nenhuma pergunta |
+| `empty_label` / `empty_text` | pergunta sem texto / conteúdo sem texto |
+| `too_long` (`limit`) | texto acima do limite daquele tipo (pergunta, ajuda, fim do intervalo, link, texto alternativo) |
+| `title_too_long` / `button_too_long` | título de tela acima de 30 / botão acima de 35 |
+| `description_too_long` | descrição de foto/arquivo/calendário acima de 300 |
+| `no_options` / `empty_option` / `option_too_long` / `option_description_too_long` | escolha sem opções / opção vazia / opção acima de 30 / descrição de opção acima de 300 |
+| `selection_invalid` | mínimo/máximo de marcações impossível |
+| `date_range_invalid` | data mínima depois da máxima |
+| `empty_end_label` / `range_helper_incomplete` / `calendar_title_too_long` | intervalo sem rótulo do fim / ajuda numa ponta só / título do calendário acima de 80 |
+| `invalid_url` / `invalid_read_more_url` | link ou "Ler mais" sem http/https |
+| `no_image` / `image_missing` | imagem sem arquivo / arquivo que não é deste formulário (suba de novo pelo `_images`) |
+| `too_many_links` / `too_many_images` / `too_many_pickers` | mais de 2 links / 3 imagens / 1 foto-arquivo na mesma tela |
+| `too_many_files` | soma de arquivos acima de 10 no formulário |
+
+  `error.kind`: `no_channel` (nenhuma caixa oficial dessa conta do WhatsApp), `busy` (publicação em andamento),
+  `duplicate_name` (nome já usado nessa conta do WhatsApp), `validation` (a Meta recusou o arquivo; a mensagem diz
+  onde), `meta`, `network`, `too_large`, `unexpected`.
+- `_update` durante uma publicação devolve 409 `busy`.
+
+### "Salvar em" (`save_targets`)
+`{"f_1": "contact.name", "f_2": "custom.cidade"}` no `_update`. Destinos: `contact.name`, `contact.email`,
+`contact.cadastral.<cpf|rg|cnpj|passport|profession|marital_status|gender|date_of_birth>`,
+`contact.address.<cep|street|number|complement|neighborhood|city|state|country>`, `custom.<chave do contato>`,
+`conversation_custom.<chave da conversa>`. O atributo precisa existir na conta (`lionchat_custom_attributes_list`)
+e não ser protegido; destino inválido = 422 (inclusive código de pergunta de foto/arquivo, ou que não existe no
+rascunho nem na última publicação). Telefone nunca. Vale na hora (não precisa publicar). Grava quando o cliente
+envia: dado novo vence, resposta em branco não apaga, valor que não cabe no tipo do atributo não grava. Pergunta
+tirada do rascunho mantém o destino até publicar de novo (a versão no ar ainda pergunta). Foto e arquivo não têm
+destino: chegam como anexo da própria mensagem de resposta.
+
+### Como a resposta chega (para ler depois)
+- Mensagem ENTRANTE na conversa do cliente, texto fixo "Formulário respondido", `content_type: form`, com
+  `content_attributes.items` (`[{name: 'f_1', label: 'Seu nome'}]`) e `content_attributes.submitted_values`
+  (`[{name: 'f_1', value: 'Maria'}]`) — leia por `lionchat_conversations_messages_list`.
+- Os valores já vêm legíveis: opção pelo nome, data DD/MM/AAAA, intervalo "DD/MM/AAAA a DD/MM/AAAA", aceite Sim/Não,
+  foto/arquivo "N arquivos: nomes" (os arquivos vêm como anexos da mesma mensagem; arquivo acima do limite de
+  recebimento fica de fora).
+- `content_attributes.whatsapp_form`: `form_id`, `publication_number`, `flow_token` e `raw` (as respostas cruas).
+  Sem nenhuma resposta: "Formulário respondido (nenhuma resposta preenchida)"; ilegível: "Formulário recebido (não
+  foi possível ler as respostas)" com `whatsapp_form.unreadable = true`.
+- A IA de atendimento lê as respostas; a resposta reabre a conversa como qualquer mensagem do cliente. Fluxo parado
+  em "Aguardar resposta" só segue depois do "Salvar em" gravar.
+
+### Armadilhas
+- **Aposentar (`_deprecate`) é irreversível** e derruba todo modelo que abre o formulário. Confirme com o usuário.
+- `_destroy` só apaga rascunho ou aposentado (publicado = `deprecate_first`).
+- `version_outdated: true` no `_show` = publicado numa versão que a Meta não aceita mais: publicar de novo.
+- `flow_id` do botão é o `meta_flow_id` (número da Meta), não o `id` nosso; o gatilho do fluxo usa o `id` nosso.
+- Imagem: só por LINK de imagem pública (página da web, endereço interno ou arquivo que não é imagem = 422
+  `fetch_failed`/`invalid_image`; acima de 10 MB = `file_too_large`).

package/dist/docs/resources/glossary.md

@@ -214,6 +214,13 @@ comportamento intencional.
 - `funnel_stage`: nome da etapa atual (string)
 - `position`: ordem dentro da etapa (inteiro)
 - `stage_entered_at`: timestamp de quando entrou na etapa atual
+- Situação (11/10/2026): `item_details.status` guarda `open`/`won`/`lost`; a resposta traz também `effective_status`
+  (`open`, **`snoozed`** = adiado, `won`, `lost`) e `snoozed_until`. **Card adiado** = card aberto que sai da coluna até
+  uma data e volta sozinho nela ("Adiar até" na tela). Ferramentas `lionchat_kanban_items_snooze`/`_unsnooze`; regras
+  em kanban-deep-dive, seção "Card adiado".
+- Venda (13/10/2026): `item_details.attributed_to` = **vendedor** do ganho ("Atribuir ganho a");
+  `item_details.co_attributed_to` = **co-participante da venda** (ex.: o SDR), só em card ganho. Regras em
+  kanban-deep-dive, seção "Co-participante da venda".
 
 ### `item_details` (jsonb)
 ```json
@@ -529,6 +536,22 @@ A plataforma opera com 6 idiomas: `en`, `es`, `fr`, `it`, `pt`, `pt_BR` (default
 brasileiras: pt_BR). Conta com idioma antigo/descontinuado cai em inglês. Notas internas geradas
 pela IA saem no idioma da conta.
 
+## Formulário do WhatsApp (WhatsappForm) — 17/10/2026
+
+Formulário NATIVO da Meta (WhatsApp Flows), preenchido DENTRO do WhatsApp e aberto por um botão FLOW num modelo
+de mensagem. Só caixa do WhatsApp Oficial. Montado no LionChat (2º tipo da área Formulários) e publicado na conta
+do WhatsApp do cliente. Ferramentas `lionchat_whatsapp_forms_*`; regras completas no resource
+`lionchat://docs/formularios-publicos`, seção "Formulário do WhatsApp". Três formulários que NÃO são a mesma coisa:
+**Formulário público** (LeadForm, página com link próprio), **Formulário do WhatsApp** (este) e **formulário de
+anúncio da Meta** (MetaLeadForm, Lead Ads).
+
+| Status | Significado |
+|---|---|
+| `draft` | rascunho, nunca publicado (pode excluir) |
+| `publishing` | publicação em andamento |
+| `published` | no ar; `unpublished_changes: true` = o rascunho mudou depois da última publicação |
+| `deprecated` | aposentado na Meta (irreversível); pode excluir |
+
 ## 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

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

@@ -141,6 +141,8 @@ Um card individual dentro de uma etapa.
 | `activities` | jsonb array — log de atividades |
 | `checklist` | **O que fica guardado:** jsonb array de tarefas do card (item: `text`/`completed`/`position` + `group_id`/`group_name` opcionais para agrupar). **O que a API devolve é OUTRA coisa** — ver o aviso logo abaixo |
 | `timer_started_at`, `timer_duration` | Timer interno do card |
+| `effective_status` | **Só na resposta, não é coluna (11/10/2026).** A situação EFETIVA do card: `open`, `snoozed` (adiado), `won` ou `lost`. `item_details.status` continua `open` num card adiado — quem quer saber se ele está adiado lê ESTE campo. Vem em `kanban_items_list`/`_show`/`_filter`/`_search`, na busca geral, na ficha do contato e no card embutido em `conversations_show`. Ver "Card adiado" no fim |
+| `snoozed_until` | **Só na resposta (11/10/2026).** Até quando o card está adiado (ISO 8601); `null` quando não está adiado |
 
 > **ATENÇÃO — na maioria das respostas o `checklist` NÃO é a lista de tarefas, e sim um resumo com
 > os números:** `{ total_count, completed_count, groups: [{ group_id, group_name, total_count,
@@ -198,9 +200,9 @@ Como gravar pelo `lionchat_kanban_items_update` (`kanban_item.item_details`):
 - Mandar objeto (`{"origem_lead": "Facebook Ads"}`) no lugar da lista **APAGA todos os campos do card**: o
   servidor só aceita itens `{name, type, value}` e o objeto vira vazio.
 - Lista fechada de chaves do `item_details` (outras são descartadas em silêncio): title, description, status,
-  reason, win_reason, loss_reason, attributed_to, duplicated_from_id, priority, value, currency,
-  custom_attributes, offers, closed_offers, closed_offer, deadline_at, scheduling_type, scheduled_at,
-  conversation_id, automations, notes.
+  reason, win_reason, loss_reason, attributed_to, co_attributed_to (13/10/2026, ver "Co-participante da venda"),
+  duplicated_from_id, priority, value, currency, custom_attributes, offers, closed_offers, closed_offer, deadline_at,
+  scheduling_type, scheduled_at, conversation_id, automations, notes.
 - Para mudar UM campo sem reenviar a lista, as ações de automação/macro `update_card_attribute`
   (`[{funnel_id, attribute_key: "<nome do campo>", value}]`) mexem só naquela entrada.
 
@@ -284,6 +286,10 @@ Log automático de eventos do card:
 
 Tipos comuns: `created`, `stage_changed`, `agent_assigned`, `agent_removed`, `note_added`, `value_changed`, `priority_changed`, `archived`.
 
+Desde 11/10/2026 também `item_snoozed` (o card foi adiado — leva `snoozed_until`) e `item_unsnoozed` (o card adiado
+abriu — leva `reason`: `person` = alguém abriu, `automation` = automação, macro ou fluxo, `due` = chegou a data; e a
+data que estava marcada).
+
 Quem fez: `by_user_id`/`user` traz a pessoa; ação de automação ou flow vem com o nome da regra/fluxo;
 ação da IA (desde 21/08/2026 — entra com o próximo deploy do app depois de 21/08/2026) vem como
 `"IA: <nome do assistente>"` com `id` nulo — antes saía sem autor. Ao explicar um histórico de card,
@@ -503,7 +509,7 @@ PUT /api/v1/accounts/43/funnels/43
 | trigger_type | trigger_value |
 |---|---|
 | `card_created` | `"card_created"` (literal — NUNCA vazio) |
-| `status_change` | `"won"` ou `"lost"` |
+| `status_change` | `"won"`, `"lost"` ou `"snoozed"` (desde 11/10/2026: roda quando o card é ADIADO; trocar a data de um card já adiado NÃO roda de novo). NÃO existe `"open"` aqui |
 | `stage_moved` | chave da etapa de DESTINO no hash `funnel.stages` (ex. `"agendar_instalacao"` — a chave, NÃO o campo `id` interno) |
 
 **Ações (`action` + `action_config`):**
@@ -647,6 +653,9 @@ Cada card pode receber atributos custom de 3 origens diferentes. **A escolha do
    `funnel_stage` com o slug que aparece em `kanban_items_show` e compare com `funnels_show`.
 3. `position` está faltando? (cards sem position vão pro fim)
 4. Está em outro funil? (mover entre funis muda `funnel_id`)
+5. Está **adiado**? (desde 11/10/2026) Card adiado sai da coluna e só aparece com o botão **Adiados** ligado no topo
+   do quadro. Confira `effective_status`/`snoozed_until` em `lionchat_kanban_items_show`: ele volta sozinho na data, ou
+   abra agora com `lionchat_kanban_items_unsnooze`. Ver "Card adiado" abaixo.
 
 ## Diagnóstico: "Valor do pipeline errado"
 
@@ -747,3 +756,77 @@ com o `retroativo_em` certo.
 
 A hora é montada em **UTC**, com o horário atual no dia escolhido. É o mesmo motivo do diagnóstico
 acima: o relatório compara o carimbo como texto, então a data escolhida tem que ser a data contada.
+
+## Card adiado — "Adiar até" (2026-10-11)
+
+O card ganha uma situação a mais: **Adiado** — "este negócio só volta a importar no dia X". Ele sai da coluna e, na
+data marcada, **abre sozinho** e volta para a coluna (disparando o fluxo "Card aberto", se houver).
+
+| Regra | Detalhe |
+|---|---|
+| O que é | Situação **do card**, não da conversa. Mensagem do cliente NÃO abre o card; adiar o card não mexe na conversa. |
+| Como fica gravado | `item_details.status` **continua `open`** — o adiamento mora numa tabela à parte (`kanban_item_snoozes`). Por isso o aplicativo de celular, os webhooks do cliente e a IA de atendimento continuam vendo `open`/`won`/`lost`. Para saber se está adiado, leia `effective_status` (`snoozed`) e `snoozed_until`. |
+| Quem pode | Quem pode editar o card. Só card **aberto** pode ser adiado (ganho/perdido = 422). |
+| Data | Pelo menos **1 hora** à frente (menos que isso = 422). Sem prazo máximo. Adiar um card já adiado **troca a data**. |
+| O que NÃO encerra | Mover de etapa ou de funil, editar, nota, tarefa, responsável. |
+| O que encerra | Marcar **ganho** ou **perdido** (por qualquer caminho); **abrir** de propósito (`lionchat_kanban_items_unsnooze`, `lionchat_kanban_items_create_2` com `status: "open"`, ação "Aberto" de automação/macro/fluxo); e a chegada da data. |
+| `status: "open"` no `lionchat_kanban_items_update` | **NÃO abre** card adiado (é o mesmo salvar que o aplicativo faz o tempo todo). Para abrir, use `lionchat_kanban_items_unsnooze` ou o `change_status`. |
+| Na data | O sistema abre o card numa rodada de até ~5 minutos depois da hora e dispara "Card aberto" **uma vez por card**. Esse fluxo entra na fila de disparos agendados: depois dos lembretes de consulta e, em caixa QR Code, no ritmo da caixa (um lote grande que vence junto sai aos poucos). |
+| "Criar card" acha um adiado | Trata como card que **já existe**: não cria outro, move se a etapa for diferente e **não muda a situação** (continua adiado). Vale para automação, macro, fluxo e IA. |
+
+**Ferramentas:**
+- `lionchat_kanban_items_snooze` — `POST .../kanban_items/{id}/snooze` com `snoozed_until`.
+- `lionchat_kanban_items_unsnooze` — `DELETE .../kanban_items/{id}/snooze` (abre agora e dispara "Card aberto").
+- Automações de dentro do funil (`settings.automations`): gatilho `status_change` com `trigger_value: "snoozed"`
+  ("Adiado" na tela do funil) roda quando o card passa de aberto para adiado.
+- Automação e macro: ação `snooze_kanban_item` — `[{"funnel_id": 31, "amount": 3, "unit": "days"}]` (`unit` `hours`
+  ou `days`; `amount` inteiro, 1 ou mais). Em regra de evento de CARD basta `[{"amount": 3, "unit": "days"}]` (o card
+  é o do evento). Diferente das outras ações de card, ela **falha visível** quando não dá para adiar (card fechado,
+  sem card no funil, tempo inválido) — nunca passa verde sem adiar.
+- Fluxo: ação `snooze_kanban_item`, gatilhos `card_opened` ("Card aberto") e `card_snoozed` ("Card adiado") e
+  condição `kanban_snoozed`. Ver o resource do FlowBuilder.
+
+**Onde o adiado aparece e como filtrar:**
+
+| Lugar | Comportamento |
+|---|---|
+| Quadro (`lionchat_kanban_items_list`) | Sem nenhum `show_*`, a lista traz TODAS as situações (o adiado vem com `status: "open"` e `effective_status: "snoozed"`). Com qualquer `show_*`: `show_open` vale `true` salvo se vier `"false"` (= aberto e **não** adiado) e `show_snoozed=true` inclui os adiados. **Só os adiados:** `show_snoozed=true` **e** `show_open=false`. Esta lista **ignora** `statuses`. |
+| Filtro rico (`lionchat_kanban_items_filter`), exportação e relatório da etapa | `statuses: ["open"]` = aberto e **não** adiado; `statuses: ["snoozed"]` = adiados. |
+| Ficha do contato (`lionchat_contacts_kanban_items_list`) | `status=snoozed` = adiados; `status=open` deixa os adiados de fora. |
+| Busca geral (`lionchat_search_kanban_items`) | `kanban_filters` com `statuses: ["snoozed"]`. |
+| Números | `lionchat_funnels_open_counts` conta aberto e **não** adiado. `lionchat_funnels_stage_report` traz a linha `snoozed` — mas esse relatório SEMPRE aplica os botões de situação com o padrão da tela: sem `show_*` conta só os abertos não adiados e as linhas `won`/`lost`/`snoozed` voltam zeradas (mande `show_won`/`show_lost`/`show_snoozed=true`). No relatório agregado (`lionchat_kanban_items_list_3`), `statusDistribution.open` **continua incluindo** os adiados (é a soma que o aplicativo lê) e `statusDistribution.snoozed` vem ao lado: abertos de verdade = `open − snoozed`. Parados, maiores negócios, ranking e previsão já deixam o adiado de fora. |
+| Histórico do card | `item_snoozed` (com a data) e `item_unsnoozed` (com o motivo). |
+
+**Laço de cadência é permitido:** um fluxo "Card aberto" que manda mensagem e adia de novo roda até alguém parar (no
+máximo uma volta por hora por card). Avise o cliente antes de montar. **Abrir à mão também dispara "Card aberto"**: se o
+fluxo manda mensagem, o cliente recebe na hora.
+
+## Co-participante da venda (vendedor + SDR) — 2026-10-13
+
+No ganho, além do vendedor (`attributed_to`, "Atribuir ganho a"), dá para marcar **UM co-participante** — ex.: o SDR
+que trouxe a venda. A venda conta INTEIRA para o vendedor; o co-participante tem números próprios no relatório.
+Marcar alguém como co-participante **não dá acesso ao card** nem o põe como responsável.
+
+**Como gravar:**
+- Junto com o ganho: `lionchat_kanban_items_create_2` (`change_status`) com `status: "won"` e `co_attributed_to: <id do
+  agente>`. Fora de `won` o parâmetro é ignorado.
+- Depois, num card JÁ ganho: `lionchat_kanban_items_update` com `kanban_item.item_details.co_attributed_to`. Para tirar,
+  mande `null`.
+- Mande SÓ o id (número). O nome (`co_attributed_name`) o próprio card preenche — nunca envie.
+- Objeto ou lista no lugar do id = 422 antes de gravar.
+
+**Recusas (422, com `error` legível):** id que não é número; pessoa que não é membro da conta; o próprio vendedor do
+card; pessoa sem acesso ao funil (vale: funil sem lista de agentes, agente da lista do funil ou dos times dele,
+administrador, ou quem já é responsável do card). A conferência só roda quando o valor MUDA — quem perdeu o acesso
+depois não trava outro salvamento.
+
+**O que mais saber:**
+- Reabrir ou marcar como perdido **apaga** o co-participante (o campo só existe em card ganho).
+- A ação "marcar como ganho" de fluxo, automação e macro NÃO marca co-participante (decisão do dono): ganho por ação
+  nasce sem ele, que entra depois pela tela, por `lionchat_kanban_items_update` ou pela planilha de "Importar vendas"
+  (coluna de co-participante, por nome ou e-mail).
+- Duplicar o card não copia o co-participante.
+- Histórico: marcado junto com o ganho vai dentro do registro da mudança de status; marcado depois gera
+  `co_participant_changed` (antes e depois, com nome e quem marcou).
+- Números: `coParticipantRanking`, `sharedSalesSummary`/`sharedSalesBySeller` (com `include_shared_sales=true`) no
+  relatório agregado e a lista `lionchat_kanban_items_shared_sales` — ver `lionchat://docs/filtros-e-relatorios` §4.