@lionchat/mcp-server 1.19.1 → 1.20.0

package/dist/docs/instructions.md

@@ -19,9 +19,11 @@ Comprovado em produção (24/07): a sessão que dizia "não há função de list
   kanban_items, funnels, flows, flow_tools, campaigns, macros, automation_rules, agents, teams,
   inboxes, labels, canned_responses, reports, sla, csat, captain_assistants, captain_documents,
   scheduled_messages, custom_attributes, webhooks, eclinica_integrations, tasks, notifications,
-  lead_forms (Formulários públicos de captação).
-- **Fora do MCP por decisão do dono (19/08): assinatura, plano, fatura, forma de pagamento, cartão,
-  saldo e recarga.** Não existem ferramentas dessas áreas e não devem ser criadas. Se o usuário
+  lead_forms (Formulários públicos de captação), signature_documents / signature_envelopes
+  (assinatura ELETRÔNICA de contratos — modelos e contratos enviados).
+- **Fora do MCP por decisão do dono (19/08): assinatura DO PLANO (cobrança), plano, fatura, forma de
+  pagamento, cartão, saldo e recarga.** (A assinatura ELETRÔNICA de contratos é outra coisa e TEM
+  ferramentas: `lionchat_signature_*`.) Não existem ferramentas dessas áreas e não devem ser criadas. Se o usuário
   pedir, diga que isso se resolve no painel, na área de assinatura da conta — não tente por
   ferramenta nem por chamada direta.
 - Só depois de pesquisar e não encontrar é que se pode dizer que a função não existe.
@@ -223,6 +225,17 @@ lionchat_conversations_messages_list (conversation_id: 123)
 3. lionchat_inboxes_public_conversations_create (vincula contato à inbox)
 ```
 
+**Telefone com ou sem o nono dígito (desde 05/09/2026):** a busca do passo 1 acha o contato
+mesmo que ele esteja salvo na OUTRA forma do celular brasileiro (com o 9 quando você busca sem, e
+vice-versa). Não precisa buscar duas vezes. Se mesmo assim `lionchat_contacts_create` devolver 422
+com `attributes: ["phone_number"]`, o contato já existe — busque de novo e ATUALIZE em vez de criar.
+Nunca tente "resolver" trocando a forma do número no create: a criação recusa as duas formas de
+propósito (a recusa protege contra ficha em dobro).
+**Atenção:** como a busca e o `contacts_filter` agora enxergam as duas formas, uma pessoa que tenha
+ficha duplicada pode voltar como **2 resultados**. Nunca pegue o primeiro às cegas para
+`contacts_update` — confira nome/e-mail ou pergunte ao usuário qual é a ficha certa. A lupa geral
+(`lionchat_search_list`) NÃO tem essa tolerância: para telefone, use `lionchat_contacts_search`.
+
 ### Criar funil (kanban) novo com etapas
 
 **FUNIL = KANBAN = pipeline = board — são a MESMA coisa no LionChat.** Quando o usuário pedir "cria um kanban", "monta um pipeline" ou "cria um funil", a ferramenta é `lionchat_funnels_create` (não existe endpoint separado de "criar kanban").
@@ -372,13 +385,14 @@ Antes de escolher a ferramenta, cheque se a intenção bate com a coluna da dire
 |---|---|---|
 | Listar / ver não lidas | `lionchat_conversations_list` (`conversation_type: 'unread'`) ou `lionchat_conversations_meta` | NÃO use `lionchat_conversations_unread` — é AÇÃO DE ESCRITA (marca como não-lida) |
 | Achar a conversa **de uma pessoa/empresa** (nome, telefone, e-mail, CPF/CNPJ, nº da conversa) | `lionchat_search_list` (`/search/conversations`) ou `lionchat_contacts_search` | RÁPIDO. **NÃO use `lionchat_conversations_search`**: apesar do nome, ele é o legado que procura dentro das mensagens e leva **15 a 22 s** (medido em produção 11/08). O sufixo `_list` aqui é histórico — `lionchat_search_list*` **são buscas**, não listagens; a regra "não baixe tudo com `*_list`" vale para `lionchat_<recurso>_list` |
-| Achar **onde foi dito** algo (palavra dentro da conversa) | `lionchat_search_list_2` (`/search/messages`) | RÁPIDO: índice trigram próprio e teto de tempo em duas fases (2 s / 14 s). É a substituta certa do `lionchat_conversations_search` |
+| Achar **onde foi dito** algo (palavra dentro da conversa) | `lionchat_search_list_2` (`/search/messages`) | RÁPIDO: índice trigram próprio e teto de tempo em duas fases (2 s / 2 s desde 04/09 — antes a 2ª fase herdava 14 s e o pior caso da seção era 16 s). Estourou as duas, o payload volta com `message_search_interrupted: true` e a lista VAZIA — isso NÃO quer dizer que não existe, quer dizer que não deu tempo: tente de novo. É a substituta certa do `lionchat_conversations_search` |
 | Não sei se o termo é nome de alguém ou algo dito no papo | `lionchat_search_search` (`/search`) | Cobre os dois numa chamada. Opção mais segura quando a intenção é ambígua |
 | (qualquer busca) termo com menos de 3 caracteres | — | Volta **vazio de propósito** em todas as buscas. Vazio ≠ "não existe": quer dizer que a busca não rodou. Refaça com 3+ caracteres. Só-dígitos é isento nas rotas `/search/*`, mas **não** no `lionchat_conversations_search` legado |
 | Só a contagem / números | `lionchat_conversations_meta` / `lionchat_reports_summary` | Não liste o conteúdo completo |
 | Criar contato | `lionchat_contacts_create` base (path `/contacts`) | NÃO use as variantes `_1` … `_9` |
 | Pausar a IA agora (botão de pânico) | `lionchat_captain_assistants_update` (`paused: true`, top-level) | — |
 | Criar/editar **formulário público de captação** (página de captura própria) | `lionchat_lead_forms_create` / `_update` | Leia `lionchat://docs/formularios-publicos` ANTES — o desenho vai em `form_data` e só entra no ar depois do `publish` (que valida o desenho e pode voltar 422 com a lista de pendências). Caixa de WhatsApp vinculada (`inbox_id`) é obrigatória pra publicar. Escrita é só de administrador |
+| **Mandar um contrato pra assinar** / ver quem assinou / reenviar / cancelar / criar ou editar o modelo escrito | `lionchat_signature_envelopes_create` / `_list` / `_show` / `_resend` / `_cancel`; `lionchat_signature_documents_list` / `_create` / `_update`; `lionchat_signature_envelopes_sign_as_sender` (o remetente assina pelo painel) | Leia `lionchat://docs/assinatura-eletronica` ANTES. Modelo `text` a API cria e edita (texto com `{{contact.*}}`); PDF/Word só pela tela. Campo do modelo sem valor na ficha bloqueia o envio (422 `variaveis_sem_valor` com a lista); `422 escolher_caixa` = repita com `inbox_id`. Cada contrato consome 1 vaga do limite mensal. Modelo Word: `422 fila_cheia` = muita gente convertendo agora, repita em instantes; `422 conversor_indisponivel` = o serviço de conversão está fora (não é o arquivo) — avise o operador. Remetente assina pelo painel com `_sign_as_sender` (PNG em base64). Importar Word, pré-visualizar e baixar PDF: só pela tela (o conector não envia arquivo nem recebe PDF) |
 | **Testar um formulário** antes de publicar | `lionchat_lead_forms_test_run` | Roda o RASCUNHO no motor real e desfaz tudo no fim — zero rastro. Mande `answers: [{node_id, value}]` (até 60) pra reproduzir um caminho; a resposta traz o bloco atual + o log do percurso |
 | Conferir se um site **aceita ser exibido dentro do formulário** (bloco Página externa) | `lionchat_lead_forms_check_embed` | Body `{url}`; devolve `{status: allowed\|blocked\|unknown, reason}`. Grave o veredito em `embed_allowed` do bloco. Admin-only |
 | Ver **tudo que uma pessoa preencheu** (nosso formulário, anúncio do Meta, Webhook Universal, fluxo) | `lionchat_contacts_form_entries_list` / `_show` | Por CONTATO, sem paginação (teto 250 por origem, `meta.truncated`). O detalhe de Meta/webhook mostra SÓ os campos vinculados e gravados — nunca o payload cru. `show` exige `source` + `id` da mesma linha |

package/dist/docs/resources/assinatura-eletronica.md

@@ -0,0 +1,75 @@
+# Assinatura eletrônica de contratos
+
+**Não confundir com "assinatura" de PLANO/cobrança** (fatura, cartão, saldo) — essa área fica fora do MCP.
+Aqui é a **assinatura eletrônica de documentos**: o cliente assina um contrato pelo WhatsApp (ou e-mail),
+com código de uso único, e o LionChat guarda a prova (IP, aparelho, localização, hash, PDF selado).
+Feature `document_signing` (ligada por conta; 403 `feature_disabled` quando desligada).
+
+## As três camadas
+
+| Camada | O que é | Ferramentas |
+|---|---|---|
+| **Modelo** (`signature_documents`) | O contrato padrão, escrito uma vez com `{{variáveis}}` da ficha. `kind`: `text` (escrito no editor — o único que a API cria), `file` (PDF pronto, igual pra todos) ou `word` (.docx que sai idêntico com os campos mapeados) — os dois últimos só pela tela (upload). | `lionchat_signature_documents_list/show/create/update/destroy/field_catalog` |
+| **Contrato** (`signature_envelopes`) | Cada ENVIO a uma pessoa: PDF próprio com os dados dela, prazo, linha do tempo. | `lionchat_signature_envelopes_list/show/create/resend/cancel/limits` |
+| **Participante** | Quem assina dentro de um contrato: `signer` (titular, pode ser mais de um), `witness` (testemunha, opcional), `sender` (o remetente, quando o modelo tem "eu também assino" — assina NO PAINEL, sem link). Cada um tem link e código próprios. | dentro do contrato (`participants[]`) |
+
+## Estados do contrato (`status`) e os baldes de filtro
+
+| Balde (`status` na listagem) | Estados | Significado |
+|---|---|---|
+| `aguardando` | `draft`, `sent` | criado sem entrega (draft) ou enviado e ainda não aberto |
+| `visualizado` | `viewed`, `partially_signed` | abriu o link / parte das pessoas já assinou |
+| `assinado` | `signed_pending_seal`, `signed` | todos assinaram; selando / documento final pronto |
+| `encerrado` | `refused`, `cancelled`, `expired` | recusado / cancelado pela equipe / prazo venceu |
+| `falta_eu` | — | contratos abertos em que o usuário do token é o remetente e ainda não assinou |
+
+Participante: `pending` → `viewed` → `verified` (confirmou o código) → `signed` | `refused`.
+
+## Linha do tempo (`events[].kind`)
+`created` · `delivered` (link entregue a uma pessoa) · `sent` · `opened` (cada abertura) · `code_requested` ·
+`code_verified` · `signed` (com `ip`, `device`, `location`; `panel: true` = assinou no painel) · `all_signed` ·
+`sealed` (documento final gerado, `sealed_sha256`) · `refused` · `cancelled` · `expired` · `delivery_failed`
+(motivo em `delivery.failed[]`) · `reminded` · `resent`. Tudo append-only — é o relatório de evidências.
+
+## Como mandar um contrato (receita)
+1. `lionchat_signature_documents_list` → escolha o modelo (ou crie um `text` com `signature_documents_create`;
+   variáveis em `signature_documents_field_catalog`).
+2. Confira a ficha: toda `{{variável}}` do modelo precisa ter valor no contato (nome, CPF, endereço…) —
+   senão o envio volta `422 variaveis_sem_valor` com a lista do que falta.
+3. `lionchat_signature_envelopes_create` com `signature_document_id`, `contact_id` e `participants`
+   (`[{name, role: 'signer', phone, delivery_channel: 'whatsapp', contact_id}]`; testemunha = mais um item
+   com `role: 'witness'` e o telefone dela).
+4. `422 escolher_caixa` → a pessoa conversa em mais de uma caixa de WhatsApp: repita com `inbox_id`.
+5. Acompanhe com `signature_envelopes_show` (linha do tempo) ou `signature_envelopes_list`
+   (`contact_id`, `status`, `q`). Não chegou? `resend`. Errou? `cancel` (admin). Falta a SUA assinatura
+   (modelo com "eu também assino")? `signature_envelopes_sign_as_sender` — ver regra abaixo.
+
+## Regras que valem sempre
+- **Quem pode**: administrador ou cargo personalizado com "Gerenciar Assinaturas" (`signature_manage`) — vale para
+  criar/editar modelo, prévia, enviar, reenviar, baixar e "eu também assino" (403 sem a chave). A LISTA de modelos e a
+  leitura de um modelo continuam abertas a qualquer membro. Cancelar contrato e apagar modelo: só administrador.
+- **Trava sagrada**: campo do modelo sem valor na ficha bloqueia o envio. Preencher a ficha primeiro.
+- **Validade** (`roles_layout.validity_days`, padrão 7) conta do ENVIO; `{{document.deadline}}` imprime a data no
+  texto; passou = `expired` (cron de hora em hora). **Lembrete** (`reminder_days`, padrão 2, 0 = off): quem não
+  assinou recebe o link de novo a cada N dias.
+- **Conversor de Word** é um serviço separado (docx-converter). Fora do ar = `422 conversor_indisponivel` na prévia e no envio de modelo Word — é o serviço, não o arquivo; repetir em instantes. Modelos `text` e `file` não passam por ele.
+- **Fila única de conversão do Word**: uma conversão por vez em toda a instalação (todas as contas); pela tela espera-se até 10 s, automação/macro/fluxo/formulário até 2 s.
+  Passou disso o envio/prévia volta `422 fila_cheia` — é só repetir em instantes (o modelo está bom).
+- **Limite mensal** (`signature_envelopes_limits`): cada contrato criado consome 1 vaga; cancelar não devolve.
+- **PDFs** (original, assinado, evidências) e o **QR de conferência** só existem pela tela/download autenticado —
+  não há ferramenta que devolva os bytes. O `sealed_sha256` é o hash do documento final.
+- **Só pela tela, de propósito** (existem na API, mas NÃO como ferramenta): importar um Word (`import_docx`),
+  pré-visualizar modelo ou rascunho (`preview`, `preview_draft`) e baixar PDF (`download`). O conector não envia
+  arquivo nem recebe PDF — não prometa "vou gerar a prévia" ou "vou baixar o assinado"; oriente a tela.
+- **Assinar no painel** ("eu também assino", 08/09): `lionchat_signature_envelopes_sign_as_sender` assina como o
+  REMETENTE (a pessoa do token) — nunca no lugar do cliente. Manda `signature_image` (PNG em base64 com prefixo
+  `data:image/png;base64,...`), opcional `location {latitude, longitude, accuracy}` (vai pra prova) e
+  `remember_drawing`. 422: `nao_e_sua` (não é o remetente deste contrato), `ja_assinado`, `sem_desenho`. Era a
+  última que faltava? o contrato fecha e o PDF final é gerado em seguida. Os que esperam você: `status=falta_eu`.
+- **Envio por outros caminhos**: ação `send_signature_document` no FlowBuilder, na Macro e na Automação;
+  bloco `generate_contract` no Formulário público (gera pelas respostas e manda o link). Gatilhos do Flow
+  `signature_*` (8 acontecimentos) trazem `{{contrato.*}}` — ver `lionchat_flows_schema_reference`.
+
+## Onde o cliente vê
+Menu **Assinaturas** (modelos e contratos, filtros, "Falta você assinar"), aba **Contratos** na ficha do contato,
+pílulas na conversa a cada acontecimento e avisos no sininho para quem enviou.

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

@@ -160,11 +160,11 @@ Travas que valem conhecer (não dá pra desligar):
 ## Limite do prompt e cache OpenAI (2026-05-22)
 
 - `config.instructions` (system prompt do agente) aceita até **20.000 caracteres** (antes 10k). Acima de 15k, o frontend mostra aviso "lost in the middle" — prefira colocar instruções críticas no início ou final.
-- **Cache automático** ativo em todos os 16 modelos oferecidos na plataforma. Desconto 50-75% no input cachado, sem configuração. Reuso do prompt do agente em múltiplas conversas maximiza a economia.
+- **Cache automático** ativo em todos os 19 modelos oferecidos na plataforma. Desconto 50-75% no input cachado, sem configuração. Reuso do prompt do agente em múltiplas conversas maximiza a economia.
 
 ### Lista real de modelos (`config.model`)
 
-Estes são os 16 valores que o seletor de modelo do painel oferece (`ModelSelector.vue`). Só recomende
+Estes são os 19 valores que o seletor de modelo do painel oferece (`ModelSelector.vue`). Só recomende
 valores desta lista:
 
 | Faixa | Modelos |
@@ -172,18 +172,21 @@ valores desta lista:
 | Econômicos / rápidos | `gpt-4.1-nano`, `gpt-4o-mini`, `gpt-4.1-mini`, `gpt-5.4-nano`, `gpt-5.4-mini` |
 | Intermediários | `gpt-4o`, `gpt-4.1`, `gpt-5-mini`, `gpt-5.4` |
 | Raciocínio | `o3-mini`, `o4-mini` |
-| Premium | `gpt-5`, `gpt-5.2`, `gpt-5.5`, `o1`, `o3` |
+| Premium | `gpt-5`, `gpt-5.2`, `gpt-5.5`, `gpt-5.6-luna`, `gpt-5.6-terra`, `gpt-5.6-sol`, `o1`, `o3` |
 
 **`GPT-5.2 Pro` não existe.** O valor válido é `gpt-5.2`, sem "Pro".
 
-> **PERIGO — família `gpt-5.6` (`gpt-5.6-luna`, `gpt-5.6-terra`, `gpt-5.6-sol`): REMOVIDA em 29/07/2026.**
-> Esses modelos **recusam function tools** em `/v1/chat/completions` (erro 400 real: "Function tools with
-> reasoning_effort are not supported"). Como o AI Agente usa ferramentas em **toda** resposta, 100% das
-> chamadas falhavam e a IA ficava **MUDA** — sem erro na tela, sem resposta. Ficou 2 semanas invisível.
-> **Nunca sugira, nunca grave** um `gpt-5.6` — nem se o cliente pedir "o mais novo/mais forte".
+> **Família `gpt-5.6` (`gpt-5.6-luna`, `gpt-5.6-terra`, `gpt-5.6-sol`) — LIBERADA em 09/2026.**
+> Foi removida em 29/07/2026 porque recusa function tools no canal antigo da OpenAI e deixava a IA MUDA.
+> Desde 09/2026 o servidor fala com esses três pela porta `/v1/responses` (só para eles — nenhum outro
+> modelo muda de canal). Podem ser gravados em `config.model` do assistente, no Copilot e no bloco de IA do
+> Flow. **Recusam temperatura personalizada: `config.temperature` é ignorada** (só o padrão). O `sol` custa
+> ~5x o `luna` — recomende o `luna` salvo pedido explícito. **NUNCA no bloco de IA do Formulário de Lead**
+> (teto de 15 s; o servidor exclui e cai no fallback).
 >
-> O campo `config.model` **não tem lista branca no servidor**: ele é `store_accessor` do `config` e
-> aceita qualquer texto sem validar. Modelo inválido salva com 200 e só quebra na hora de responder.
+> Desde 09/2026 o campo `config.model` **tem lista branca no servidor** (`LlmConstants::SELECTABLE_MODELS`):
+> trocar para um modelo fora da lista devolve **422** (`model is not included in the list`). Registro
+> antigo com modelo fora da lista continua salvando os outros campos; só a troca é recusada.
 > Desde 29/07 o erro vira uma **nota privada em português** na conversa (`llm_request_rejected`) — é o
 > primeiro lugar a olhar quando "a IA parou de responder logo depois de mexerem nas configurações".
 
@@ -872,3 +875,16 @@ Custom attribute em lugar errado vira:
   passageiro — o socorro cuida; reenviar por cima entrega em dobro.
 - **Filtros de data fixa cortam o dia no fuso da CONTA** (padrão America/Sao_Paulo) — e mudar o
   `timezone` da conta move essa fronteira.
+
+## Editar o PRÓPRIO agente (02/09/2026)
+
+`agents_update` passou a aceitar que a pessoa edite a si mesma — **times e caixas liberados**. Antes
+nem a tela oferecia: um administrador não conseguia se colocar nem se tirar de um time ou de uma caixa.
+
+**A trava:** ninguém muda o próprio **cargo** (nem o perfil base, nem o cargo personalizado). O
+servidor recusa com 422 e a mensagem *"Você não pode alterar o próprio cargo. Peça a outro
+administrador."* — a recusa é `before_action`, então NADA do resto do update é aplicado junto.
+
+Ao atualizar o próprio usuário: mande times e caixas à vontade; **não mande `role` nem
+`custom_role_id`** — se mandar, a chamada inteira falha e as outras alterações se perdem também.
+Para trocar o cargo de alguém, use a conta de OUTRO administrador.

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

@@ -724,3 +724,20 @@ Os limites que a API devolve (`resource_limits.*` da conta, `email_usage.limit`,
 duas contas no MESMO plano podem ter limites diferentes — não é defeito. Limite `0` significa
 ILIMITADO em toda a plataforma. A contratação/remoção de adicionais é feita SÓ pela tela de
 Cobrança do painel (não há ferramenta MCP para isso, por decisão do dono).
+
+## Assinatura eletrônica de contratos (04/09)
+
+```
+SignatureDocument (modelo)  1 ──── N  SignatureEnvelope (contrato de UMA pessoa)  1 ──── N  SignatureParticipant
+   name, kind (text|file|word)            title, status, sent_at, expires_at,                name, role (signer|witness|sender),
+   body ({{variáveis}}), tags,             contact_id, conversation_id,                       status, phone/email, delivery_channel,
+   roles_layout {signers, witnesses,       original_sha256, sealed_sha256,                    conversation_id (a conversa DELE),
+   sender_signs, require_id_photo,         created_by (quem mandou)                           public_url, signed_at, viewed_at
+   validity_days, reminder_days}                │
+   progress (contagem por balde)                └── N  SignatureEvent (append-only: kind, occurred_at, ip, user_agent, detail)
+```
+- Contrato aponta pro contato (`contact_id`, nulifica se a ficha for apagada — a prova sobrevive) e pra conversa
+  do titular; cada participante tem a PRÓPRIA conversa (testemunha na dela).
+- `roles_layout` é jsonb aberto e MESCLADO no update; `progress` é calculado (aguardando/visualizado/assinado/encerrado).
+- Feature por conta: `document_signing`. Limite mensal em `usage_limits.signature_requests_per_month` (0 = ilimitado).
+- Detalhe completo: resource `lionchat://docs/assinatura-eletronica`.

package/dist/docs/resources/filtros-e-relatorios.md

@@ -79,7 +79,7 @@ Mesmo shape de condição. 15/página.
 |---|---|
 | `id` (id interno do contato) | equal_to, not_equal_to |
 | `name`, `email`, `identifier`, `city`, `company`, `profession` | equal_to, not_equal_to, contains, does_not_contain |
-| `phone_number` | + starts_with (busca por DDD/prefixo) — **corrigido na atualização de 26/07/2026**; em instalação anterior devolve SEMPRE lista vazia (virava igualdade exata). Vazio com prefixo que existe = instalação antiga |
+| `phone_number` | + starts_with (busca por DDD/prefixo) — **corrigido na atualização de 26/07/2026**; em instalação anterior devolve SEMPRE lista vazia (virava igualdade exata). Vazio com prefixo que existe = instalação antiga. **`equal_to`/`not_equal_to` casam as DUAS formas do celular BR (com e sem o 9º dígito) desde 05/09/2026** — mande `+5541999887766` ou `+554199887766`, os dois acham a mesma ficha; `not_equal_to` exclui as duas. Termo que não é celular BR completo (fixo, estrangeiro, trecho) segue exato |
 | `cpf`, `cnpj`, `rg` (cadastral) | equal_to, not_equal_to, contains, does_not_contain, is_present, is_not_present |
 | `country_code` | equal_to, not_equal_to |
 | `labels` | equal_to, not_equal_to, is_present, is_not_present |
@@ -297,3 +297,41 @@ número/data em texto; array-de-objetos em query (padrão B exige JSON-string);
 `custom_attribute_type` quando contato e conversa têm atributo de mesmo nome; esperar paginação
 no kanban_items_filter (não tem — estreite o filtro); montar um `custom_dashboards_update` em cima
 de uma listagem que veio cortada (apaga os blocos que não chegaram).
+
+## Filtro de DATA do Kanban (02/09/2026) — `kanban_items_filter` e `funnels_stage_report`
+
+Quatro eixos de data, cada um com **janela fixa** (`_start`/`_end`, ISO) OU **atalho relativo**
+(`_relative` + `_relative_days`). Formato FLAT (o Kanban não usa o shape `payload` dos outros filtros).
+
+| Eixo | Chaves | O que recorta |
+|---|---|---|
+| Criação do card | `date_start`/`date_end` · `date_relative`/`date_relative_days` | quando o card foi criado |
+| Entrada na etapa | `stage_date_start`/`_end` · `stage_date_relative`/`_days` | quando entrou na etapa ATUAL |
+| Atualização | `updated_date_start`/`_end` · `updated_date_relative`/`_days` | última alteração do card |
+| Ganho/perdido em | `closed_date_start`/`_end` · `closed_date_relative`/`_days` | data do desfecho |
+
+**Operadores do atalho** (`*_relative`): `today`, `yesterday`, `last_days`, `days_ago`, `days_before`.
+- `today` e `yesterday` **não levam número** — não mande `_relative_days` com eles.
+- `last_days` = os últimos N dias **incluindo hoje** (N=7 → de 6 dias atrás até o fim de hoje).
+- `days_ago` = o dia exato de N dias atrás. `days_before` = mais de N dias atrás (janela aberta à esquerda).
+- **N inteiro de 1 a 998.** Texto, zero, negativo, decimal ou maior que 998 é recusado.
+- A janela é calculada no **fuso da conta** (não em UTC).
+
+Os quatro eixos são independentes e podem ser combinados. Janela fixa e atalho no mesmo eixo:
+mande só um dos dois.
+
+> **CUIDADO — operador inválido NÃO dá erro, ALARGA o resultado.** Se `*_relative` vier com um
+> operador fora da lista, ou `last_days`/`days_ago`/`days_before` sem número válido, o atalho é
+> **ignorado em silêncio**: a resposta volta com MAIS cards (até 5.000) e a tela ainda mostra o selo
+> de "filtrado". Como o quadro tem **ação em massa, inclusive excluir**, nunca use o retorno de um
+> filtro de data para uma ação destrutiva sem conferir a contagem antes. (Em condição de ATRIBUTO o
+> comportamento é o oposto e seguro: valor inválido fecha o filtro e devolve vazio.)
+
+Exemplo — cards que entraram na etapa atual nos últimos 7 dias, no funil 12:
+```json
+{ "funnel_id": 12, "stage_date_relative": "last_days", "stage_date_relative_days": 7 }
+```
+Cards ganhos ou perdidos ontem:
+```json
+{ "closed_date_relative": "yesterday" }
+```

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

@@ -385,6 +385,16 @@ só pra destravar, ela pode sair.
 | `pagetrack_visited` / `pagetrack_event` | LionTrack |
 | `sla_check` | status do SLA da conversa (usa `value` = código fixo; ver abaixo) |
 
+> **ATENÇÃO — onde o VALOR vai (defeito real de 02/09/2026, conta 137):** no nó **Condição**, uma regra de atributo
+> (`valueType: "attr_config"`) com operador `equal`, `not_equal`, `contains` ou `not_contains` guarda o valor em
+> **`values: ["..."]` (lista)** e deixa `value: ""`. A TELA lê SÓ a lista: regra gravada com `value: "paid_ad"` e
+> sem `values` roda certa no motor mas abre com a caixa de valor **VAZIA** — o cliente conclui que não foi
+> configurado. Só `greater_than`, `less_than`, `starts_with` e `ends_with` usam `value` (campo único);
+> `number_range` usa `value: "min-max"`; `is_empty`/`is_not_empty` não têm valor. Grave sempre o shape completo:
+> `{ "id": 1, "field": "{{last_response}}", "operator": "equal", "value": "", "values": ["paid_ad"],
+> "valueType": "attr_config", "attrSource": "conversation", "attrScope": "campaign", "attr_key": "origin_kind",
+> "funnel_id": "", "stage": "" }` dentro de `rules`, com o branch repetindo `value`/`values`/`valueType`.
+
 **Restrição por TIPO de atributo (a UI só oferece um subconjunto, e é o que faz sentido):**
 - **Texto/string:** `equal`, `not_equal`, `contains`, `not_contains`, `starts_with`, `ends_with`, `is_empty`, `is_not_empty`
 - **Número:** `equal`, `not_equal`, `greater_than`, `less_than`, `number_range`, `is_empty`, `is_not_empty`
@@ -427,6 +437,8 @@ campanha"):
 - Caso real (Cast, 01/09): flow "Ativar IA" só para lead de anúncio = condição `origin_kind equal paid_ad`
   na saída `cond_0` + ação `assign_captain` nessa saída; `default` sem nada.
 
+- **`attrScope: "lead_origin"` (02/09/2026):** preset "Origem do lead" da aba Conversas — mesmo shape do `campaign_attr`, ja nasce com `attr_key: "origin_platform"`. Valores: plataformas fixas (`facebook`, `google`...) ou origem cadastrada como `custom:<slug>`. O motor ignora `attrScope`; sem ele a regra reabre como "Atributo de campanha" (falha macia).
+
 **Agente de IA — `conversation_has_ai_agent` e irmãos (novo 2026-08-01):** o flow sempre soube LIGAR e
 DESLIGAR a IA (ações `assign_captain` / `deactivate_captain`), mas não sabia PERGUNTAR se ela estava
 ligada. Agora sabe. É o espelho exato do trio do agente humano:
@@ -504,7 +516,7 @@ o botão "Usar variável" ao lado do campo alterna lista fixa ↔ variável.
 | `remove_conversation_label` | `{ labels: ['slug'] }` | Remove labels da CONVERSA |
 | `mute_conversation` | `{}` | Silencia notificações |
 | `mark_unread` | `{}` | Marca a conversa como NÃO LIDA pro time (espelho do `mute_conversation`; típico logo após `assign_agent`/`assign_team` numa transferência) |
-| `add_private_note` | `{ content: 'texto' }` | Adiciona nota interna |
+| `add_private_note` | `{ text: 'texto' }` | Adiciona nota interna. **A chave é `text`** — é a que o formulário do bloco lê (`v-model="item.config.text"`). Até 04/09 esta linha dizia `content`, e por isso 56 blocos de 8 contas abriam VAZIOS na tela: a nota era gravada (o motor tem rede) mas ninguém conseguia ler nem editar o texto. `content` continua sendo aceito e normalizado para `text` na gravação |
 | `create_kanban_item` | `{ funnel_id, funnel_stage, title?, description? }` | Cria card no Kanban — `funnel_id` e `funnel_stage` OBRIGATÓRIOS; `title`/`description` aceitam variáveis `{{ }}` |
 | `move_kanban_item_to_stage` | `{ funnel_stage }` | Move card (precisa ter card vinculado) |
 | `move_kanban_stage` | `{ funnel_id, funnel_stage }` | Idem |
@@ -512,12 +524,12 @@ o botão "Usar variável" ao lado do campo alterna lista fixa ↔ variável.
 | `set_won` | `{}` | Atalho pra ganho |
 | `set_lost` | `{ reason? }` | Atalho pra perdido |
 | `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` | `{ content }` | Nota no card |
+| `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) |
 | `add_card_offer` | `{ offer_id, use_custom_value?, custom_value?, funnel_id?, card_source? }` | Adiciona uma OFERTA (produto/serviço) ao card. `offer_id` de `offers_list`. `use_custom_value: true` + `custom_value` grava um valor personalizado na oferta; senão usa o valor cadastrado. O total do card recalcula sozinho (soma das ofertas). Respeita `card_source` (funnel só localiza o card) |
 | `send_webhook` | `{ url, headers?, body? }` | Dispara webhook externo |
 | `start_flow` | `{ flow_id }` | Inicia outro fluxo. **NÃO encerra o fluxo de origem** (desde 31/08): se houver bloco ligado depois dele, o fluxo SEGUE normalmente. Sendo o último do desenho, o fluxo termina ali como sempre. |
-| `send_conversion` (novo 2026-09-01) | `{ destinations: ['meta'\|'ga4'\|'google_ads'], event_name, value? }` | Manda o evento de conversão pro Meta (CAPI), Google Ads e/ou GA4 — o mesmo caminho do Funil, de dentro do fluxo. Aba Sistema (só flow `conversation`). Ver bloco próprio abaixo |
+| `send_conversion` (novo 2026-09-01; `event_names` 2026-09-02) | `{ destinations: ['meta'\|'ga4'\|'google_ads'], event_names: { meta?, google_ads?, ga4? }, event_name (reserva), value? }` | Manda o evento de conversão pro Meta (CAPI), Google Ads e/ou GA4 — o mesmo caminho do Funil, de dentro do fluxo. Aba Sistema (só flow `conversation`). Ver bloco próprio abaixo |
 | `deactivate_flow` ou `disable_flow` | `{}` | Encerra fluxo atual |
 | `update_attribute` | `{ attr_source: 'contact'\|'conversation'\|'card', attr_key, attr_value }` | Seta custom_attribute (ver abaixo) |
 | `assign_captain` (ou `assign_captain_assistant`) | `{ assistant_id }` | Atribui IA Captain |
@@ -530,7 +542,7 @@ o botão "Usar variável" ao lado do campo alterna lista fixa ↔ variável.
 **`send_conversion` — Enviar conversão (2026-09-01):**
 
 ```json
-{ "key": "send_conversion", "config": { "destinations": ["meta", "google_ads"], "event_name": "Lead", "value": "1500,50" } }
+{ "key": "send_conversion", "config": { "destinations": ["meta", "google_ads"], "event_names": { "meta": "Lead", "google_ads": "Contact" }, "event_name": "Lead", "value": "1500,50" } }
 ```
 
 - `destinations`: array com `meta`, `ga4` e/ou `google_ads` — **OBRIGATÓRIO e não vazio** (vazio = a ação
@@ -539,7 +551,11 @@ o botão "Usar variável" ao lado do campo alterna lista fixa ↔ variável.
   (o histórico do fluxo mostra "GA4: pulado (integração não configurada, evento não mapeado ou pausado)").
   Confira antes com `lionchat_meta_pixel_integrations_list`, `lionchat_google_ads_integrations_list`,
   `lionchat_ga4_integrations_list`.
-- `event_name`: **OBRIGATÓRIO**, só letras/números/sublinhado (até 40; ex.: `Lead`, `Schedule`,
+- `event_names` (**desde 2026-09-02**): um evento POR destino marcado — `{ "meta": "Lead", "google_ads": "Contact", "ga4": "generate_lead" }`.
+  Chave presente e em branco = aquele destino é PULADO ("sem nome de evento"); chave ausente cai em `event_name`.
+  Google Ads só envia evento que tenha ação mapeada na integração; a tela lista Meta (padrão + personalizados
+  da conta) e Google Ads (mapeados), GA4 é livre. Grave sempre `event_names` E `event_name` (= primeiro nome).
+- `event_name`: reserva/compatibilidade (fluxos de antes de 02/09), só letras/números/sublinhado (até 40; ex.: `Lead`, `Schedule`,
   `Purchase`); aceita variável `{{ }}`. No **Google Ads** o nome precisa estar mapeado no
   `conversion_action_map` da integração, senão é pulado.
 - `value` (opcional): número (vírgula BR aceita, `1500,50`) ou variável. **Vazio = valor do CARD** (ver
@@ -656,13 +672,15 @@ aiModel nos modos novos (proteção de nós antigos que carregam aiModel de defa
 padrão da conta).
 Exemplo: `{"aiMode":"sentiment","aiAssistantId":"12","aiModel":"gpt-4.1-mini","aiModelExplicit":true}`.
 
-**A whitelist (`FlowBuilder::RawLlmService::SUPPORTED_MODELS`) é uma lista FECHADA de 16 nomes, SEM
+**A whitelist (`FlowBuilder::RawLlmService::SUPPORTED_MODELS`) é uma lista FECHADA de 19 nomes, SEM
 curinga** — não existe "a família gpt-5 inteira":
 `gpt-4o-mini`, `gpt-4o`, `gpt-4.1-nano`, `gpt-4.1-mini`, `gpt-4.1`, `gpt-5-mini`, `gpt-5`,
-`gpt-5.2`, `gpt-5.4-nano`, `gpt-5.4-mini`, `gpt-5.4`, `gpt-5.5`, `o1`, `o3`, `o3-mini`, `o4-mini`.
-A família **`gpt-5.6` (luna/terra/sol) foi REMOVIDA em 2026-07-29**: ela recusa function tools
-(erro 400 na OpenAI), o que deixava o Agente de IA **mudo em 100% das chamadas** — saiu também daqui
-pra não ser oferecida numa tela e faltar na outra. Também não existem `o1-mini`, `gpt-4.5-preview`,
+`gpt-5.2`, `gpt-5.4-nano`, `gpt-5.4-mini`, `gpt-5.4`, `gpt-5.5`, `gpt-5.6-luna`, `gpt-5.6-terra`,
+`gpt-5.6-sol`, `o1`, `o3`, `o3-mini`, `o4-mini`.
+A família **`gpt-5.6` (luna/terra/sol) voltou em 09/2026** (tinha sido removida em 2026-07-29 porque
+recusa function tools no canal antigo): o servidor fala com esses três pela porta `/v1/responses`.
+Eles ignoram a temperatura do bloco (só o padrão) e **NÃO valem no bloco de IA do Formulário de Lead**
+(teto de 15 s — o servidor exclui e usa o fallback). Também não existem `o1-mini`, `gpt-4.5-preview`,
 `gpt-5.2-pro` nem `gpt-5.5-pro` (a OpenAI recusa).
 
 **OBRIGATÓRIO via API — `aiAssistantId`:** os modos `generate`/`intent`/`sentiment`/`extract`
@@ -928,10 +946,35 @@ Node terminal, sem handles de saída. **EXCLUSIVO de flow `ai_tool`** — NUNCA
 no último node, sem node de fim. Em `ai_tool` é OBRIGATÓRIO: o `data` do `end` define o que
 volta pro LLM (modo de saída + template do resultado).
 
+Campos do `data`:
+
+| Campo | Valores | Default | O que faz |
+|---|---|---|---|
+| `mode` | `template`, `auto`, `silent` | `template` | como o resultado volta pro LLM |
+| `template` | texto Liquid (`{{ params.x }}`, `{{ contact.x }}`) | vazio | SÓ no modo `template` |
+| `include_log` | `true`/`false` | `false` | SÓ no modo `auto` — anexa o log da execução ao JSON |
+
+- **`template`** — devolve o texto Liquid renderizado, precedido de um cabeçalho que MANDA a IA
+  cumprir aquilo neste turno. É o modo do "diga isso ao cliente".
+- **`auto`** — devolve JSON com `params`, `variables` e `status`. Dado, não ordem.
+- **`silent`** (desde 02/09/2026) — **encerra o turno sem resposta da IA**. Use quando o próprio
+  fluxo já enviou a mensagem final pelo bloco de mensagem: sem isso a IA fala de novo por cima e
+  duplica a informação. A IA continua ATIVA e responde normalmente a próxima mensagem do cliente.
+
 ```json
-{ "id": "node-end", "type": "end", "position": { "x": 1330, "y": 300 }, "data": { "label": "Retorno", "mode": "structured" } }
+{ "id": "node-end", "type": "end", "position": { "x": 1330, "y": 300 }, "data": { "label": "Retorno", "mode": "template", "template": "Orçamento enviado. Confirme o recebimento com o cliente." } }
 ```
 
+```json
+{ "id": "node-fim-mudo", "type": "end", "position": { "x": 1330, "y": 520 }, "data": { "label": "Fim sem resposta", "mode": "silent" } }
+```
+
+**ATENÇÃO:** `mode` aceita SÓ os três valores acima. Até 02/09/2026 esta página ensinava
+`mode: "structured"`, que NENHUMA tela produz e NENHUM leitor entende — o motor trata valor
+desconhecido como `template`, e sem `template` a IA recebe **string vazia**. Se você criou algum
+`end` com `structured` (ou qualquer outro valor), troque por um dos três. Mesma família do gatilho
+do bloco Início que a documentação do MCP ensinou errado (19/08).
+
 ### 2.14 `note` (anotação visual / sticky note colorido)
 
 Sticky note no canvas (aquele bloco colorido riscado na tela pra rotular/agrupar). Puramente visual: sem handles, NUNCA executado (não ligue edges nele). Disponível nos DOIS tipos de flow (`conversation` e `ai_tool`).

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

@@ -23,7 +23,7 @@ caixa de WhatsApp vinculada e (opcionalmente) dispara um fluxo do FlowBuilder no
   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
+- **Escrita é de administrador ou de cargo personalizado com "Gerenciar Formulários" (`lead_form_manage`).** `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.
@@ -145,6 +145,21 @@ Seguranças: o valor pulado **nunca aparece na tela nem no payload público**, e
 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.
 
+**Toggle "Reconhecer quem recebeu o link"** (`settings.identify_by_link`, default `true` — inclusive
+para formulário antigo, que não tem a chave). Desligado, o formulário **ignora o carimbo por
+completo**: a resposta nasce anônima e cada pessoa preenche do zero.
+
+Existe para o formulário **repassado**: o carimbo identifica o contato PARA QUEM o link foi enviado,
+então, se essa pessoa encaminha o link (caso real: formulário que o cliente manda para os
+familiares), todos abrem como se fossem ela — e o `ContactLinker` grava atributo personalizado, dado
+cadastral e etiqueta de **todos na mesma ficha** (`apply_to_linked_contact`). O sintoma visível é só
+o pulo das perguntas; o estrago real é no cadastro.
+
+O corte acontece no **nascimento da resposta** (`identified_contact_id`, no controller público), não
+no `WalkService`. Desligar apenas o pulo das perguntas seria conserto pela metade: a resposta
+continuaria nascendo com o `contact_id` errado. A chave **não vai** para o payload público (a
+whitelist do `metadata` segue sem ela) — a decisão é do servidor.
+
 ## O contrato do `form_data`
 
 ```json
@@ -179,6 +194,7 @@ roda anônimo normal. Link copiado do editor e colado fora de uma conversa NÃO
 | `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) |
+| `generate_contract` | `label, document_id, send_link` | `success`, `error` | 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
@@ -303,6 +319,16 @@ respostas já dadas como contexto. `model` é validado contra a lista suportada;
 da conta. A IA usa a **chave da própria conta** — conta sem chave faz o bloco sair pela saída de
 erro.
 
+**`generate_contract`** (04/09 — bloco "Gerar contrato", feature `document_signing`): gera o CONTRATO de
+assinatura eletrônica daquela pessoa a partir de um modelo (`document_id` = id de
+`lionchat_signature_documents_list`) com os dados da FICHA — mapeie as perguntas com `map_to` para os
+campos que o modelo usa (nome, CPF, endereço…); campo sem valor = saída `error` com o motivo
+(`variaveis_sem_valor: contact.cpf`). `send_link` (padrão `true`) manda o link de assinatura no WhatsApp da
+pessoa (conversa da caixa vinculada); `false` deixa o contrato pronto e você manda `{{contrato.<node_id>.link}}`
+pelo bloco `send_message`. Roda DEPOIS do vínculo do contato, como efeito (bloco de espera), dentro dos
+orçamentos do formulário (200 contratos/formulário/dia, 2.000/conta/dia). Consome 1 vaga do limite mensal
+de contratos. Saídas: `success` (contrato criado) e `error`.
+
 ### Variáveis
 
 | Variável | O que traz | Onde vale |
@@ -311,6 +337,7 @@ erro.
 | `{{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 |
+| `{{contrato.<node_id>.link}}` `.titulo` `.prazo` `.id` `.status` | O contrato gerado pelo bloco Gerar contrato (endereço de assinatura, título, data-limite) | mensagem, prompt, valores |
 | `{{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 |
 

package/dist/docs/resources/glossary.md

@@ -150,8 +150,8 @@ DESCARTADAS na entrada (não criam conversa nem notificam). Bloquear NÃO resolv
 - `Channel::Whatsapp` — WhatsApp Cloud API (oficial)
 - `Channel::WebWidget` — chat ao vivo no site
 - `Channel::Email` — email
-- `Channel::FacebookPage` — Messenger
-- `Channel::Instagram` — Instagram DM
+- `Channel::FacebookPage` — Messenger; com `medium: "instagram"` é uma caixa **só de Instagram** conectada pela Página do Facebook (trate como Instagram)
+- `Channel::Instagram` — Instagram DM (login pelo Instagram)
 - `Channel::Telegram` — Telegram
 - `Channel::Api` — webhook custom
 - `Channel::Voice` — VoIP / chamadas
@@ -533,3 +533,73 @@ Termos do formulário (18/08):
 Detalhes completos (construtor, página pública, blocos, gatilhos de flow, tetos e limites) no
 resource `lionchat://docs/formularios-publicos`.
 
+## Histórico importado virou A conversa (02/09/2026)
+
+Antes, a conversa trazida do celular (importação) e a conversa viva do mesmo contato eram DUAS. A
+atendente escrevia da conversa de arquivo, o cliente respondia e a resposta abria uma terceira. Agora:
+
+- **Um contato, uma conversa por caixa.** A mensagem que chega ADOTA a conversa que já existe —
+  importada ou não — e a reabre. Os importadores escrevem na conversa do contato.
+- **A conversa é lida por DATA, não por número** (paginação e as leituras da IA mudaram juntas).
+- **`live_since`** marca quando a conversa passou a ter atendimento de verdade. Relatório de
+  resolução e SLA contam desse marco, nunca da data importada.
+- **Janela de 24h, reativação e seletor de modelo olham a última fala VIVA do cliente.** Conversa só
+  de arquivo, sem resposta, segue com a janela FECHADA — mandar texto livre nela falha.
+- **Adoção NÃO dispara "conversa criada".** Fluxo/automação/IA presos nesse gatilho não rodam na
+  adoção; o gatilho equivalente é **"Conversa reaberta"**.
+- Histórico importado continua fora do contexto da IA e não infla o contador do resumo pago.
+
+### Chaves reservadas do sistema — API e MCP não gravam mais
+
+`ConversationBuilder` passou a RECUSAR as chaves de `Conversation::RESERVED_ADDITIONAL_KEYS` vindas de
+fora ao criar conversa: `imported_from`, `import_digits`, `mail_subject`, `type`, `in_reply_to`,
+`initiated_by`, `auto_reply`, `original_channel_type`, `conversation_language`,
+`agent_reply_time_window`, `conference_sid`, `call_status`, `tiktok_capabilities`,
+`captain_media_asset_id`, `live_since`, `has_imported_history`.
+
+Não tente mandá-las em `additional_attributes` ao criar conversa — são ignoradas. Gravar `live_since`
+com data futura ou `has_imported_history` fecharia a janela de 24h daquela conversa para sempre.
+
+## Campos novos na resposta da API (02/09/2026)
+
+| Campo | Onde | Para que serve |
+|---|---|---|
+| `medium` | caixa (`inboxes_list`/`_show`) | sub-tipo do canal. Numa caixa de Página do Facebook diz se ela é Messenger ou **só Instagram** — é o que separa os dois |
+| `content` | mensagem | já vem no formato de exibição (mensagem apagada mostra o aviso, não o texto cru) |
+| `last_incoming_message_at` | conversa | data da última mensagem VIVA do cliente (unix). Use para saber se a janela de 24h está aberta — não confie na data da conversa, que pode vir de histórico importado. Mensagem que a Meta entregou ATRASADA (reentrega depois de uma queda) conta pela hora de ENVIO da Meta, não pela chegada (08/09): o campo, `can_reply` e a tela seguem a mesma régua que a Meta usa pra recusar |
+
+## Formulário público: código para incorporar no site (02/09/2026)
+
+Além do link público, o formulário passou a ter um **código para embutir no site do cliente** (iframe
+gerado na tela do formulário) e um **interruptor para desligar o reconhecimento do link repassado** —
+quando ligado, um link identificado enviado numa conversa pula os campos já conhecidos; desligado, o
+formulário sempre pergunta tudo. Use quando o cliente reclamar que o formulário "já vem preenchido"
+para a pessoa errada (link repassado a terceiros).
+
+## Gravação de ligação do VTCall (02-03/09/2026)
+
+A gravação permanente só nasce cerca de 24h depois da ligação. O card agora entra com a gravação
+**conferida** (o arquivo é sondado antes de virar link) e é reconferido por até 36h; ligação
+**recebida** passou a ter gravação, e o card é atualizado em silêncio (sem sino, sem reabrir a
+conversa). Quem atendeu voltou a aparecer nas recebidas. Se o cliente diz que o botão de ouvir não
+funciona numa ligação de hoje, o mais provável é que o arquivo permanente ainda não exista — a
+reconferência resolve sozinha dentro de 36h.
+
+## Assinatura eletrônica de contratos (04/09)
+
+### `status` do contrato (`signature_envelopes`)
+| Valor | Balde de filtro | Significado |
+|---|---|---|
+| `draft` | aguardando | criado sem nenhuma entrega (falhou) — use `resend` |
+| `sent` | aguardando | link entregue, ninguém abriu ainda |
+| `viewed` | visualizado | alguém abriu o link |
+| `partially_signed` | visualizado | parte das pessoas assinou |
+| `signed_pending_seal` | assinado | todos assinaram; o documento final está sendo gerado |
+| `signed` | assinado | documento final pronto (`sealed_sha256`) |
+| `refused` / `cancelled` / `expired` | encerrado | recusado / cancelado pela equipe / prazo venceu |
+
+### `role` do participante: `signer` (titular), `witness` (testemunha), `sender` (remetente — assina no painel).
+### `status` do participante: `pending` → `viewed` → `verified` → `signed` | `refused`.
+### Erros do envio (`signature_envelopes_create`): `variaveis_sem_valor` (+ `missing[]`), `escolher_caixa` (+ `inboxes[]`),
+`entrega_falhou`, `sem_caixa_whatsapp`, `telefone_invalido`, `limite_do_mes`, `cpf_invalido`, `funcionalidade_desligada`,
+`fila_cheia` (fila única de conversão do Word cheia — repetir em instantes), `conversor_indisponivel` (o serviço de conversão de Word não respondeu — repetir em instantes).