@lionchat/mcp-server 1.8.1 → 1.10.0

package/dist/docs/instructions.md

@@ -227,9 +227,15 @@ POST /api/v1/accounts/{account_id}/kanban_items
 ### Relatório de produtividade
 ```
 1. lionchat_reports_summary (visão geral)
-2. lionchat_reports_list (por agente — passa since/until ISO 8601)
+2. lionchat_reports_list (por agente — passa since/until em Unix EM SEGUNDOS)
 3. Comparar avg_first_response_time entre agentes
 ```
+**`since`/`until` dos relatórios só aceitam número Unix em SEGUNDOS** (`1782864000` = 01/07/2026 00:00
+UTC), nunca ISO 8601 nem data por extenso — o formato ISO do resto da plataforma (seção 3) NÃO vale
+aqui. Desde 29/07/2026 a API recusa com HTTP 400 (`invalid_date_params`); antes disso o relatório
+voltava ZERADO com HTTP 200 (a conta 19 tinha 4.396 conversas no período e a resposta vinha zero).
+Converta a data do usuário para segundos antes de chamar. Os exports em CSV (agents, inboxes, labels,
+teams, conversations_summary) exigem as DUAS pontas; nos demais, `since` ou `until` sozinho é válido.
 
 ### Criar campanha de WhatsApp (disparo em massa)
 ```
@@ -242,6 +248,24 @@ POST /api/v1/accounts/{account_id}/kanban_items
 Estrutura do audience: `[{type:'Label', id}, {type:'Funnel', id, stages:[], include_won, include_lost}, {type:'ConversationAttribute', key, value}]`.
 QR Code aceita `template_params` com `delay_min/delay_max/variations` (anti-bloqueio) e `bulk_actions`.
 
+### Criar campanha de FLUXO (dispara um flow, não uma mensagem) — novo 28/07/2026
+```
+1. lionchat_flows_list com with_campaign_trigger=true&inbox_id=N → flows ELEGÍVEIS
+   (vazio? o flow precisa do gatilho 'campaign_trigger' no bloco start — ver flowbuilder-design-guide)
+2. Montar audience + lionchat_campaigns_estimate_audience → mostrar contagem ao usuário
+3. CONFIRMAR com o usuário (é envio em massa — seção 7b)
+4. lionchat_campaigns_create com flow_id + template_params {delay_min, delay_max, daily_cap}
+   (SEM message — o texto sai dos blocos do flow)
+5. Acompanhar com lionchat_campaigns_flow_report; parar com lionchat_campaigns_stop_flow
+```
+A campanha inicia o flow para cada pessoa do público, cadenciado (intervalo sorteado entre uma pessoa
+e outra) e com teto de PESSOAS por dia — quem passa do teto entra no dia seguinte, no mesmo horário,
+automaticamente. Vale nas duas famílias de WhatsApp (oficial e QR Code).
+
+Ao explicar o resultado, use `flow_report`: `fired` (disparados), `pending` (na fila) e `skips` (quem
+foi pulado, com o motivo). Motivo mais comum: `sessao_ja_ativa` = a pessoa já estava nesse mesmo flow,
+e pular evita que ela receba tudo em dobro. Quem está sendo atendido pela equipe **não** é pulado.
+
 ### Criar ferramenta da IA (ai_tool)
 ```
 1. lionchat_flow_tools_create (tool_name snake_case + tool_description + flow_data com nó end)
@@ -274,11 +298,15 @@ QR Code aceita `template_params` com `delay_min/delay_max/variations` (anti-bloq
 | Limite | Valor |
 |---|---|
 | `per_page` max | 100 |
-| Bulk actions (IDs) max | 100 por chamada |
+| Bulk actions (IDs) max | 300 por chamada (desde 18/05/2026; passou disso = HTTP 422 `bulk_ids_limit_exceeded`) |
 | Rate limit leitura | 1200/min por token |
 | Rate limit escrita | 600/min por token |
 | Loop detection | bloqueia chamada idêntica >10x em 10s |
 
+Exceção ao teto de 300: em ação em massa de **contatos** com `select_all: true` (agir sobre todos os
+contatos do filtro) não há teto de IDs — o servidor refaz o filtro e processa em lotes no fundo. O
+teto de 300 vale para o caminho normal, com a lista de IDs. Kanban usa o mesmo teto no `item_ids`.
+
 ## 7. Confirmar antes de agir — regra de ouro
 
 Antes de QUALQUER ação que escreve, modifica, apaga ou envia, pare e avalie se o pedido está claro e completo. Na dúvida, pergunte — **nunca chute**.

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

@@ -349,17 +349,27 @@ Quando rate-limited:
 
 ### Bulk actions
 
-`POST /bulk_actions` aceita arrays de IDs. **Máximo 100 IDs por chamada**.
+`POST /bulk_actions` aceita arrays de IDs. **Máximo 300 IDs por chamada** (`MAX_BULK_IDS`, desde
+2026-05-15). Acima disso o servidor recusa com `422` + `code: "bulk_ids_limit_exceeded"` — quebre em
+chamadas de 300.
+
+**Exceção:** contato com `select_all: true` (agir sobre TODOS os contatos do filtro) **não tem teto** —
+o servidor resolve pelo próprio filtro (`query` / `labels_filter`), em lotes no fundo, e não usa `ids`.
 
 ```json
 {
   "type": "Conversation",
-  "ids": [1, 2, 3, ...],   // max 100
-  "action_name": "assign_agent",
-  "action_attributes": { "assignee_id": 6 }
+  "ids": [1, 2, 3, ...],          // max 300
+  "fields": { "assignee_id": 6 }  // conversa: status, assignee_id, team_id, inbox_id, captain_assistant_id
 }
 ```
 
+**⚠️ `action_attributes` NÃO EXISTE.** O servidor não lê esse campo em lugar nenhum (só aparece em
+comentário de TODO no código). Mandar a mudança por ali devolve **200 OK e não faz absolutamente nada** —
+falha silenciosa, sem erro na tela. Conversa se altera por `fields` (+ `labels: {add:[], remove:[]}` e
+`snoozed_until`). Em conversa o `action_name` é **ignorado**; ele só tem efeito em **contato**, onde
+`"delete"` apaga os contatos (sem ele, o que vale é `labels: {add: []}`).
+
 ### Search (overhaul 2026-06-10)
 
 `GET /search?q=texto` — busca cross-entidade (conversations, contacts, messages, articles, kanban_items)

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

@@ -77,7 +77,14 @@ Conversa com 200 mensagens? **Não baixe tudo**:
 ## Operações em massa
 
 Pra atribuir labels, mover cards, etc em vários itens:
-- `kanban_bulk_bulk_actions` (cards Kanban)
+
+- `kanban_bulk_bulk_actions` — **NÃO é de cards do Kanban**, apesar do nome. Ela bate em
+  `POST /bulk_actions` e age em **conversas ou contatos** (o `type` é `Conversation` ou `Contact`).
+  Usar ela achando que move card não dá erro visível — só não faz o que você queria.
+- Cards do Kanban têm **três** ferramentas próprias, uma por ação:
+  - `kanban_bulk_create` → `bulk_move_items` (mover cards de etapa)
+  - `kanban_bulk_create_1` → `bulk_assign_agent` (definir o responsável)
+  - `kanban_bulk_create_2` → `bulk_set_priority` (definir a prioridade)
 - `kanban_items_kanban_agents_create` em massa (passar array)
 - `automation_rules_*` (criar regras em vez de fazer manualmente)
 
@@ -127,7 +134,32 @@ O `config` DEVE ser enviado como **objeto** (ex.: `config: { disabled_tools: [..
 ## 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 15 modelos suportados (GPT-4.1 Nano até GPT-5.2 Pro, o1, o3, o4-mini). Desconto 50-75% no input cachado, sem configuração. Reuso do prompt do agente em múltiplas conversas maximiza a economia.
+- **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.
+
+### Lista real de modelos (`config.model`)
+
+Estes são os 16 valores que o seletor de modelo do painel oferece (`ModelSelector.vue`). Só recomende
+valores desta lista:
+
+| Faixa | Modelos |
+|---|---|
+| 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` |
+
+**`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".
+>
+> 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 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".
 
 ## Follow-up automático multi-etapa (2026-06)
 
@@ -137,21 +169,61 @@ O follow-up do AI Agente agora suporta **cadência de até 3 etapas** via `confi
 { "config": { "feature_follow_up": true, "follow_up_steps": [
   { "after_minutes": 30,  "prompt": "Pergunte gentilmente se ainda tem interesse" },
   { "after_minutes": 240, "prompt": "Ofereça tirar dúvidas" },
-  { "after_minutes": 1140, "prompt": "Última tentativa, despeça-se cordialmente" }
+  { "after_minutes": 1110, "prompt": "Última tentativa, despeça-se cordialmente" }
 ] } }
 ```
 
-Regras: cada etapa ≥ 5 min; soma total ≤ 1440 min (24h); máx 3 etapas. Campos legados
-`follow_up_time` + `follow_up_prompt` continuam funcionando como 1 etapa única.
+Regras: cada etapa ≥ 5 min; **soma total ≤ 1380 min (23h)**; máx 3 etapas. Campos legados
+`follow_up_time` + `follow_up_prompt` continuam funcionando como 1 etapa única (e obedecem ao **mesmo
+teto de 1380**).
+
+> **O teto é 1380, não 1440** (`Captain::Assistant::FOLLOW_UP_MAX_TOTAL_MINUTES`). Motivo: a janela de
+> 24h do WhatsApp conta a partir da **mensagem do cliente**, não do primeiro acompanhamento — 1h de
+> folga evita agendar uma cobrança que a Meta recusaria na hora de enviar. Montar a cadência somando
+> 1440 faz o salvamento ser **recusado**. Pegadinha: a mensagem de erro do campo legado `follow_up_time`
+> ainda diz "must be between 5 and 1440 minutes", mas a validação usa 1380 — não confie no texto do erro.
+
+(O exemplo acima soma exatamente 1380: 30 + 240 + 1110.)
+
 Dispara quando o CLIENTE fica inativo após resposta da IA. O motor de follow-up é dedicado e
 **só-leitura** (não executa ferramentas, não coleta dado — só redige a mensagem de retomada,
 com saída estruturada garantida). `paused=true` no assistente corta os follow-ups também.
 
-**Corrigido em 2026-07-24:** quando a IA é ativada por um **Flow** (ação "Ativar IA") ou por uma
-**automação**, o follow-up agora é agendado no ato da ativação. Antes, nesses dois caminhos a
-cadência simplesmente nunca começava — a conversa ficava com IA ativa e sem nenhum follow-up. Se um
-cliente relatar "a IA nunca faz o follow-up", confira primeiro se a ativação veio por flow/automação
-e se a conta já está na versão de 24/07.
+### "A IA nunca faz o follow-up" — o conserto é de 29/07, NÃO de 24/07
+
+**Não repita que isso foi corrigido em 24/07.** A versão de 24/07 agendava o follow-up **dentro** do
+bloco do "Responder na hora": ou seja, ela só funcionava quando esse interruptor estava **LIGADO** —
+justamente o caso que menos precisa dela. Com "Responder na hora" **desligado**, a IA não fala, o único
+outro gatilho (o hook de mensagem enviada) também não dispara, e a conversa fica **com IA ativa e sem
+nenhum acompanhamento, para sempre**. Aconteceu em **140 conversas da conta 52** — todas criadas
+DEPOIS do suposto conserto de 24/07. A ativação **manual pela tela** nunca esteve coberta em nenhuma
+das duas versões até 29/07.
+
+**"Responder na hora" e acompanhamento são INDEPENDENTES.** São perguntas diferentes:
+- *Responder na hora* (`captain_reply_now` / `proactive`) = "a IA fala agora, sem esperar o cliente?"
+- *Acompanhamento* (`feature_follow_up`) = "a IA cobra depois, se ninguém responder?"
+
+Desligar o primeiro **não** deve desligar o segundo. Nunca oriente o cliente a ligar "Responder na
+hora" para o acompanhamento funcionar.
+
+**Corrigido de verdade em 2026-07-29**, nos três caminhos que ativam a IA, com o agendamento **fora**
+do bloco do "Responder na hora":
+- Flow, ação "Ativar IA" (`FlowBuilder::ActionDelegator`) — só em ativação nova (a conversa não tinha IA)
+- Automação, ação "Atribuir assistente" (`AutomationRules::ActionService`)
+- Ativação manual pela tela da conversa (`ConversationsController`) — armado **antes** da checagem do
+  "Responder na hora"
+
+**Ainda descoberto (não corrigido):** ativar a IA em **lote** (ação em massa de conversas com
+`captain_assistant_id`) **não arma o acompanhamento nem dispara resposta imediata**. Se o cliente
+ativou a IA em massa e reclama que ela não cobra de volta, é isso — e o caminho é reativar pela tela
+ou por automação.
+
+Diagnóstico, nesta ordem, quando relatarem "a IA nunca faz o follow-up":
+1. `config.feature_follow_up` está ligado no assistente? E `paused` está desligado? (`paused=true`
+   corta os follow-ups)
+2. A ativação veio por **lote**? Então nunca foi armado.
+3. Tem `follow_up_skip_conditions` batendo (etiqueta, atributo, janela de silêncio)?
+4. A soma das etapas passa de 1380 min? Nesse caso o assistente nem salvou a cadência.
 
 ## Condições para NÃO fazer follow-up + horário de silêncio (2026-07)
 

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

@@ -98,17 +98,65 @@ Avaliação:
 
 ### 4. Auto-assignment
 
-Roda após automation rules. Lógica simplificada:
+Roda após automation rules. Existem **DOIS caminhos vivos** (`Inbox#auto_assignment_v2_enabled?`),
+não um moderno e um legado:
 
 ```
-SE inbox.enable_auto_assignment_v2:
-  SE inbox.assignment_policy associada:
-    → Política decide (round-robin, balanced, etc)
-  SENAO:
-    → assignee_id fica null (manual)
+SE inbox.assignment_policy vinculada:
+  → modo POLÍTICA: round-robin ou balanced, prioridade da fila, capacidade
+SENÃO SE inbox.enable_auto_assignment (botão "Distribuição automática" da própria caixa):
+  → modo SIMPLES: round-robin entre os membros da caixa
+SENÃO:
+  → assignee_id fica null (atribuição manual)
 ```
 
-V2 (Assignment Policy) é o motor moderno. V1 (campo `auto_assignment` simples) é legado.
+Os dois caminhos rodam no MESMO serviço (`AutoAssignment::AssignmentService`), usam o MESMO rodízio
+(`AutoAssignment::RoundRobinSelector` — só a política pode trocá-lo pelo modo `balanced`) e passam
+pelo MESMO freio de rajada
+(`AutoAssignment::RateLimiter`). O que muda é de onde vem a configuração: com política vinculada, ela
+manda em tudo (inclusive em "distribuir para agentes offline"); sem política, vale o que está no
+`auto_assignment_config` da própria caixa.
+
+**NUNCA escreva que o modo simples é legado, nem recomende criar Política de Atribuição para quem só
+quer o botão da caixa.** Vincular uma política **esconde a seção inteira de Distribuição Automática da
+tela da caixa** (`CollaboratorsPage.vue`: `showAutoDistribution = !inbox.has_assignment_policy`). O
+cliente perde os controles que estava usando, não entende por que sumiram, e o que ele configurou lá
+passa a ser ignorado (o valor fica gravado e só volta a valer se a política for desvinculada).
+
+Regra prática:
+- Cliente quer só "dividir os leads entre a equipe" → **botão da própria caixa**. Não crie política.
+- Cliente quer regra compartilhada entre várias caixas, modo balanced, prioridade de fila ou limite de
+  capacidade por atendente → aí sim Política de Atribuição.
+
+Quem entra no rodízio: só `inbox_members` com `auto_assignable: true` (supervisor de caixa fica de
+fora) e, se "distribuir para agentes offline" estiver desligado, só quem está online.
+
+**LEIA o valor da conta antes de responder — NUNCA recite um número de cabeça.** Os valores reais
+vêm na resposta da API:
+- `has_assignment_policy` (resposta da caixa) diz QUAL dos dois caminhos vale ali. `true` = política
+  manda; `false` = vale o botão da própria caixa.
+- Com política vinculada, leia `fair_distribution_limit` (quantas conversas por atendente),
+  `fair_distribution_window` (tamanho da janela, **em segundos**) e `assign_offline_agents` na
+  resposta da política. O `auto_assignment_config` da caixa é **IGNORADO** nesse caso — não o cite.
+- Sem política, leia as MESMAS chaves dentro do bloco `auto_assignment_config` da caixa
+  (`fair_distribution_limit`, `fair_distribution_window`, `assign_offline_agents`).
+- Chave ausente/vazia = vale o padrão de fábrica (hoje 10 conversas a cada 600 segundos) — cite isso
+  só como "valor de fábrica, confira o da conta", nunca como se fosse a configuração do cliente.
+
+**EXCEÇÃO SEM FREIO (não dá pra descobrir lendo a resposta):** caixa **sem** política vinculada, com
+`assign_offline_agents` LIGADO e **sem número escolhido** em `fair_distribution_limit`, roda **SEM
+FREIO NENHUM** (`AutoAssignment::RateLimiter#resolve_limit`: `return 0 if inbox.assign_offline_agents?`).
+Racional (decisão do dono 29/07): com offline ligado todo membro está sempre na roleta, então a divisão
+já é igual por construção e o freio só atrasaria a entrega. Não existe campo dizendo "sem freio" — o
+bloco vazio parece "padrão", mas não é. Efeito prático: **nessas caixas, dizer ao cliente que existe um
+teto por atendente é MENTIRA**. Número escolhido pelo cliente sempre vence o toggle: se
+`fair_distribution_limit` tem um número MAIOR QUE ZERO, o freio existe mesmo com offline ligado.
+
+**Zero também é "sem freio":** na caixa (não na política), `fair_distribution_limit: 0` é a saída
+explícita de quem não quer teto nenhum — o freio fica desligado (`RateLimiter#enabled?` exige limite
+positivo). Ou seja, existem DUAS formas de a caixa ficar sem freio: campo vazio com offline ligado, ou
+zero escrito de propósito. Na Política de Atribuição o zero nem é aceito (o cadastro exige maior que
+zero), então política vinculada SEMPRE tem freio.
 
 ### 5. Captain (IA Agente)
 
@@ -138,7 +186,10 @@ handoff consultor→gestor). Pendente só acontece por ação explícita:
 - Ferramenta nativa da IA (deixar conversa pendente)
 
 Comportamentos importantes:
-- Mensagem nova do cliente NÃO reabre conversa pendente (segue pendente na lista)
+- Mensagem nova do CLIENTE REABRE conversa pendente (volta pra Aberta, com pílula de aviso na
+  conversa). Só a do cliente: resposta do ATENDENTE não reabre. Vale desde 30/07/2026 e REVOGA a
+  regra anterior de 20/07 ("pendente não reabre") — decisão do dono depois de a conta 19 acumular
+  258 clientes esperando sem o time ver. NUNCA responda que a conversa fica parada em Pendente
 - Pendente ATRIBUÍDA notifica o responsável (o gestor recebe o aviso)
 
 ### 7. Resolução (status 1)
@@ -186,10 +237,20 @@ Conversation
 
 ### "Conversa não atribuiu ninguém"
 
-1. `inbox.enable_auto_assignment_v2` está true?
-2. `inbox.assignment_policy` está setado?
-3. Tem `InboxMember` ativos pra essa inbox?
-4. Tem `automation_rule` que poderia ter atribuído antes?
+1. A distribuição está ligada em ALGUM dos dois caminhos? `inbox.assignment_policy` vinculada **ou**
+   `inbox.enable_auto_assignment` true. Não existe campo `enable_auto_assignment_v2` — não peça por ele.
+   Política vinculada **não é requisito**: caixa sem política e com o botão ligado distribui normalmente.
+2. Se há política: ela está com `enabled: true`? Política desligada = ninguém é atribuído.
+3. Tem `InboxMember` com `auto_assignable: true`? Supervisor de caixa é membro mas **não entra** no rodízio.
+4. Se "distribuir para agentes offline" está desligado, tem alguém **online** agora? Sem ninguém online
+   a fila fica parada até alguém logar.
+5. O atendente pode estar no **teto da janela** do freio de rajada (o robô só entrega N conversas por
+   atendente/caixa dentro de uma janela deslizante). A vaga volta quando a conversa é resolvida, adiada
+   ou vira pendente — e a fila anda sozinha em até 1 minuto. Antes de culpar o freio, confira os
+   valores reais da conta e a exceção SEM FREIO (seção 4) — pode não haver teto nenhum ali.
+6. Se a caixa tem **uma única** conversa esperando, o freio **nem se aplica** (`should_apply_rate_limit?`
+   exige mais de 1 não atribuída). Nesse caso a causa é outra — não culpe o freio.
+7. Tem `automation_rule` que poderia ter atribuído antes?
 
 ### "IA não respondeu"
 

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

@@ -245,15 +245,23 @@ Captain::Assistant
 ├── config (jsonb) — chaves principais:
 │     model, temperature, instructions (max 20.000 chars), feature_memory, feature_faq,
 │     feature_follow_up (bool), follow_up_steps (array de {after_minutes, prompt} — ATE 3 etapas,
-│       cada uma >= 5 min, soma <= 1440 min/24h; legado follow_up_time+follow_up_prompt = 1 etapa),
+│       cada uma >= 5 min, soma <= 1380 min = 23h (2026-07-29 — NAO 1440: a janela de 24h do WhatsApp
+│       conta da MENSAGEM DO CLIENTE, nao do 1o follow-up, entao 1440 disparava com a janela ja fechada.
+│       Somar 1440 = 422. GOTCHA: no campo legado follow_up_time a mensagem de erro do servidor ainda
+│       diz "must be between 5 and 1440 minutes" por engano — o teto que ele aplica e 1380);
+│       legado follow_up_time+follow_up_prompt = 1 etapa),
 │     follow_up_skip_conditions (array — condicoes pra NAO fazer follow-up, logica OU, ate 3; tipos:
 │       label {operator present|absent, labels[]}; contact_attr/conversation_attr {attribute, operator
 │       equal|not_equal|contains|present|blank|gt|lt, value}; time_window {start, end — horas inteiras
 │       0-23; NAO envia follow-up nesse periodo, janela circular ex 22->7; a IA SEGUE respondendo o
 │       cliente normal — o silencio e so do follow-up}),
-│     feature_pause_on_human_reply (bool — a IA se DESLIGA sozinha na conversa quando um HUMANO
-│       assume: atendente responde pelo painel (ao vivo) OU mensagem enviada do celular. NAO conta:
-│       nota privada, msg da propria IA, automacao, campanha, confirmacao de agendamento, msg agendada),
+│     feature_pause_on_human_reply (bool, nasce DESLIGADO — quando ligado, a IA se DESLIGA sozinha na
+│       conversa quando um HUMANO assume: atendente responde pelo painel (ao vivo) OU mensagem enviada
+│       do celular. NAO conta: nota privada, msg da propria IA, automacao, campanha, confirmacao de
+│       agendamento. MENSAGEM AGENDADA DEPENDE DE QUEM AGENDOU (2026-07-29): agendada pela IA (a tool
+│       carimba source_type='Captain::Assistant' e o disparo assina como o assistente) NAO desliga;
+│       agendada por ATENDENTE assina como User com Current.user setado no disparo = conta como
+│       atendente ao vivo e DESLIGA a IA da conversa),
 │     activation_label (etiqueta que ativa o agente — unica por conta),
 │     min_response_time / max_response_time (delay humanizado, 1-60s),
 │     disabled_tools (array de IDs de tools desativadas pro assistente),

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

@@ -60,7 +60,7 @@ Todo node tem essa estrutura base:
 }
 ```
 
-**Triggers válidos:** `message_received`, `message_sent`, `conversation_created`, `conversation_resolved`, `conversation_reopened`, `label_added`, `label_removed`, `card_created`, `card_moved`, `conversation_attribute_changed`, `card_attribute_changed`, `contact_attribute_changed`, `date_trigger`, `cron`, `webhook`.
+**Triggers válidos:** `message_received`, `message_sent`, `conversation_created`, `conversation_resolved`, `conversation_reopened`, `label_added`, `label_removed`, `card_created`, `card_moved`, `conversation_attribute_changed`, `card_attribute_changed`, `contact_attribute_changed`, `date_trigger`, `campaign_trigger`, `cron`, `webhook`.
 
 **Trigger `message_sent` (novo 2026-06-11):** par do message_received, mas pra mensagens de SAÍDA — dispara quando atendente, celular (eco do WhatsApp) ou a própria IA/flow envia mensagem (nota privada NÃO dispara). Config: `keywords` (opcional) + `match_type` (`contains`|`exact`). Caso de uso clássico: "quando eu responder do celular, desligar a IA". ATENÇÃO: mensagem da IA também dispara — se a ação for desativar a IA, use keywords que só humanos digitam ou aceite que a primeira resposta da IA aciona o flow. Protegido por anti-loop (profundidade 5) e sessão única por conversa+flow; nunca alimenta `waiting_input`.
 
@@ -95,6 +95,35 @@ Todo node tem essa estrutura base:
   - **`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.
   - **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
+por uma **Campanha de Fluxo** (Campanhas > Fluxo). É uma **AUTORIZAÇÃO, não um evento**: sozinho ele
+nunca dispara nada — quem dispara é a campanha, pessoa por pessoa, no ritmo configurado nela.
+
+Item (sem `config`): `{ "key": "campaign_trigger" }`
+
+- **Sem esse item o flow NÃO aparece na lista da campanha** e `campaigns_create` com `flow_id` responde
+  422. É o passo que todo mundo esquece — ao montar um flow para disparo em massa, **ligue este gatilho
+  antes de criar a campanha**.
+- Pode conviver com outros gatilhos no mesmo flow (ex.: um flow que responde a mensagem E também pode
+  ser disparado em campanha). É **isento** da trava de gatilho duplicado.
+- Só flow de conversa (`flow_type: conversation`); flow de grupo funciona, mas o público é de contatos.
+- Em caixa WhatsApp **oficial**, o primeiro bloco de mensagem de **CADA CAMINHO** que sai do Início
+  precisa abrir com **template aprovado** — não só o primeiro bloco que o flow encontra. Com
+  randomizador (teste A/B) ou condição logo no começo, **todas** as variações são conferidas: basta
+  UMA sem template pra campanha ser recusada na criação (422). O erro nomeia os blocos culpados pelo
+  rótulo, teto de 5: `must start with an approved WhatsApp template on official inboxes (no template
+  in: <rótulos>)`. O que vale é o **primeiro item** do `messageItems` daquele bloco, e os tipos
+  aceitos são `template` (o que a tela grava) e `whatsapp_template` (legado). Flow sem nenhum bloco
+  de mensagem não tem o que validar. Em QR Code não existe essa regra.
+  (Corrigido em 2026-07-29: até então a checagem aceitava só `whatsapp_template` — nome que a tela
+  NUNCA gravou — e olhava um caminho só; recusava 100% das caixas oficiais.)
+- Como a campanha inicia o flow com o contato **sem ter mandado nada**, escreva o 1º bloco assumindo
+  contato frio (apresente-se, dê contexto) — diferente de um flow de atendimento, que responde a alguém.
+
+Receita completa: `flows_create`/`flows_update` com o item no start → `flows_list` com
+`with_campaign_trigger=true&inbox_id=N` para confirmar que ficou elegível → `campaigns_create` com
+`flow_id`. Acompanhar: `campaigns_flow_report`. Interromper: `campaigns_stop_flow`.
+
 **Trigger `webhook` — Webhook Universal EMBUTIDO (novo 2026-06):** o flow pode ser disparado por um webhook próprio, criado automaticamente. Receita via API:
 1. Criar o flow normalmente (`flows_create`).
 2. `POST /custom_webhook_integrations` com `{ "custom_webhook_integration": { "flow_id": <id do flow> } }` — o sistema cria a integração embutida (idempotente: repetir retorna a mesma; nome automático "Flow: <nome>"; auto-mapeia todos os eventos → este flow) e retorna a URL única do webhook.
@@ -102,7 +131,7 @@ Todo node tem essa estrutura base:
 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.
 
-**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` e `manual_trigger`.
+**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).
 - Ao **ativar** (`flows_toggle` inativo→ativo) ou **criar já ativo**: qualquer conflito é barrado.
 - Ao **editar** um flow já ativo: só conflito NOVO é barrado (duplicados que já existiam são preservados).
 - A API responde **422** com `{ "error_code": "flow_trigger_conflict", "conflicts": [{ flow_id, flow_name, trigger_type, inbox_id, inbox_name }] }`.
@@ -363,7 +392,7 @@ o botão "Usar variável" ao lado do campo alterna lista fixa ↔ variável.
 
 | Key | config esperado | Efeito |
 |---|---|---|
-| `assign_agent` | `{ agent_id }` | Atribui agente humano à conversa. `agent_id` aceita id fixo OU variável Liquid — ver nota abaixo |
+| `assign_agent` | `{ agent_id }` | Atribui agente humano à conversa. `agent_id` aceita id fixo, variável Liquid (ver nota abaixo) OU a string `'nil'` — que REMOVE o responsável da conversa (opção "Nenhum" da UI) |
 | `distribute_agents` | `{ agents: [{ agent_id }], dist_id }` | RODÍZIO (round-robin) de agentes: cada lead vai pro PRÓXIMO da lista na vez (1,2,3,1,2,3). `dist_id` = id fixo da ação (chave do cursor no Redis; gere um único por ação, ex. `"d_ab12cd"`). Ordem da lista = ordem do rodízio; sem porcentagem. DIFERENTE do randomizer mode `distribute_agents` (que é sorteio ponderado) |
 | `assign_team` | `{ team_id }` | Atribui time. `team_id` aceita id fixo OU variável Liquid — ver nota abaixo |
 | `change_status` | `{ status: 'open' \| 'resolved' \| 'pending' \| 'snoozed' }` | Muda status da conversa |
@@ -380,7 +409,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 |
-| `assign_agent_card` | `{ agent_id }` | Atribui agente ao card |
+| `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_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) |
@@ -397,6 +426,10 @@ o botão "Usar variável" ao lado do campo alterna lista fixa ↔ variável.
 
 **`update_attribute` — campos EXATOS:** `attr_source` (`'contact'`, `'conversation'` ou `'card'`), `attr_key` (nome do atributo), `attr_value` (valor). NÃO existem `entity`/`key`/`value` — esses são ignorados e não salvam nada.
 
+**Coerção por TIPO (2026-07-29):** em `attr_source: 'contact'|'conversation'`, o `attr_value` de atributo personalizado é coagido pelo tipo da definição antes de gravar: número/moeda/porcentagem viram numérico ("1.234,56" → 1234.56; inteiro fica inteiro), checkbox aceita sim/não/true/false e grava BOOLEANO, lista casa caixa-insensível e grava a opção canônica, data aceita DD/MM/AAAA ou ISO, hora aceita "14:30"/"14h30". Valor irreconhecível grava como veio e o passo mostra nota âmbar no histórico. Card NÃO coage (atributo de card não tem definição tipada no backend).
+
+**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).
+
 **Somar/subtrair NÃO é operação dedicada** — é filtro Liquid no próprio `attr_value`. O valor é resolvido como template antes de salvar. Exemplos:
 
 ```json
@@ -476,14 +509,22 @@ NÃO existe `.payload`/`.response` (`{{api_response.payload.x}}` resolve vazio).
 
 **Modelo por ação — `aiModel` + `aiModelExplicit` (2026-07-13):** TODO modo aceita escolher o modelo
 LLM no próprio nó, com ou sem assistente, em qualquer tipo de flow. Enviar o par:
-`"aiModel": "gpt-4.1-mini"` (whitelist de `FlowBuilder::RawLlmService::SUPPORTED_MODELS` — ex.
-gpt-4o-mini, gpt-4o, gpt-4.1, gpt-4.1-mini, gpt-4.1-nano, gpt-5*, o1, o3*, o4-mini) JUNTO de
-`"aiModelExplicit": true`. SEM a flag o backend ignora o aiModel nos modos novos (proteção de nós
-antigos que carregam aiModel de default nunca honrado). `aiModel` vazio/ausente = modelo padrão da
-conta. Com assistente selecionado, o override também vale (sobrepõe o modelo que o caminho do
-assistente usaria). Modelo fora da whitelist = ignorado (cai no padrão da conta).
+`"aiModel": "gpt-4.1-mini"` JUNTO de `"aiModelExplicit": true`. SEM a flag o backend ignora o
+aiModel nos modos novos (proteção de nós antigos que carregam aiModel de default nunca honrado).
+`aiModel` vazio/ausente = modelo padrão da conta. Com assistente selecionado, o override também vale
+(sobrepõe o modelo que o caminho do assistente usaria). Modelo fora da whitelist = ignorado (cai no
+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
+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-pro` nem `gpt-5.5-pro` (a OpenAI recusa).
+
 **OBRIGATÓRIO via API — `aiAssistantId`:** os modos `generate`/`intent`/`sentiment`/`extract`
 EXIGEM um `aiAssistantId` válido (id de um assistente Captain da conta). Sem ele o nó SAI cedo
 (`action: continue`) sem gravar nada — a variável de saída (`aiResponseVar`/`ai_intent`/`ai_sentiment`)
@@ -560,15 +601,22 @@ O campo raiz é **`waitMode`**: `"duration"` (default), `"date"` ou `"weekday"`.
     "waitMode": "weekday",
     "waitWeekday": 1,
     "waitWeekdayTime": "09:00",
+    "waitWeekdayTimeMode": "fixed",
     "waitTimezone": "America/Sao_Paulo"
   }
 }
 ```
 
-- `waitWeekday`: 0=domingo, 1=segunda... 6=sábado. `waitWeekdayTime` = `"HH:MM"` 24h, **SEMPRE fixo** (este campo NÃO aceita variável — decisão de produto). `waitTimezone` = mesmo campo do modo date.
+- `waitWeekday`: 0=domingo, 1=segunda... 6=sábado. `waitWeekdayTime` = `"HH:MM"` 24h. `waitTimezone` = mesmo campo do modo date.
+- **Variável no Horário (novo 2026-07-29 — reverte a proibição de 06/07):** o campo `waitWeekdayTime` ACEITA variável `{{ }}`, com o mesmo contrato dos campos do modo `date`. O modo mora em **`waitWeekdayTimeMode`**: `"fixed"` (default, e o que vale quando a chave está ausente) ou `"variable"` — espelho exato do `waitTimeMode`.
+  - **Mandar a variável SEM `"waitWeekdayTimeMode": "variable"` não funciona e não avisa:** o motor trata o campo como texto fixo, a chave `{{ }}` nunca é resolvida e o horário calculado não é o pretendido. Não há erro de validação, nem na API nem na tela. Como o MCP escreve o JSON do fluxo direto, sem passar pela tela, esse par é obrigatório.
+  - Exemplo: `{"waitMode":"weekday","waitWeekday":1,"waitWeekdayTime":"{{contact.custom_attribute.horario_retorno}}","waitWeekdayTimeMode":"variable","waitTimezone":"America/Sao_Paulo"}`.
+  - Resolve UMA única vez, na entrada do node (quem já está esperando mantém o valor capturado). Aceita `"14:30"`, `"9:30"`, `"14h30"`, `"14h"`, `"14:30:00"` — ou seja, atributo tipo `time` (Hora 24h). Valor ISO de atributo `date`/`datetime` é rejeitado (mesma regra do campo Horário do modo `date`).
+  - Variável que não resolve pra horário válido → saída `error` (payload `invalid_variable_datetime`, `field: waitWeekdayTime`).
+  - Modo `fixed` NUNCA emite erro: horário em branco cai no default `09:00` — flow antigo intacto.
 - (Os nomes `targetWeekday`/`targetHour` NÃO existem — eram um erro de documentação antiga.)
 
-**Handles que SAEM:** `success` (+ `error`, emitido apenas quando um campo em modo `variable` resolve pra valor inválido no modo `date`).
+**Handles que SAEM:** `success` (+ `error`, emitido quando um campo em modo `variable` resolve pra valor inválido — vale nos DOIS modos, `date` e `weekday`; em modo `fixed` o `error` nunca é emitido).
 
 ### 2.9 `set_variable`
 
@@ -600,13 +648,19 @@ O campo raiz é **`waitMode`**: `"duration"` (default), `"date"` ou `"weekday"`.
     "label": "A/B test mensagem",
     "mode": "branches",
     "branches": [
-      { "id": "A", "label": "Variante A", "weight": 50 },
-      { "id": "B", "label": "Variante B", "weight": 50 }
+      { "id": "A", "label": "Variante A", "percent": 50 },
+      { "id": "B", "label": "Variante B", "percent": 50 }
     ]
   }
 }
 ```
 
+**O campo é `percent`, NÃO `weight` (2026-07-30):** a tela sempre gravou `percent` (`randomizerBranches`
+do FlowNodeConfigModal) e o motor lia só `weight` — nenhum node configurado pela tela funcionava.
+Corrigido em 30/07: o motor lê `percent` e aceita `weight` só como dado antigo. **Escreva sempre
+`percent`** — randomizador criado com `weight` até roda, mas abre com as porcentagens EM BRANCO na
+tela do cliente (a tela lê só `percent`).
+
 **Modo `distribute_agents` (sorteio PONDERADO):** `data.mode: 'distribute_agents'` + `data.agents: [{ agent_id, percent }]` — sorteia UM agente por probabilidade (percentuais somando 100) e atribui automaticamente. Isso é SORTEIO, não rodízio: no curto prazo pode cair no mesmo agente várias vezes seguidas. Pra RODÍZIO EXATO (cada um na vez), use a AÇÃO `distribute_agents` no node `action` (ver seção 2.5) — não este modo.
 
 **Handles que SAEM:** o `id` de cada branch (`A`, `B`, ...). Em `mode: 'distribute_agents'` é `success`.

package/dist/docs/resources/glossary.md

@@ -214,7 +214,10 @@ os de `user_ids` viram membros comuns. A resposta traz `is_supervisor` (boolean)
 - `config.feature_memory`: gera notas no contato ao resolver conversas
 - `config.feature_faq`: gera FAQs sugeridas ao resolver conversas
 - `config.feature_follow_up` + `config.follow_up_steps`: follow-up automático em cadência de até
-  3 etapas (cada ≥5 min, soma ≤24h) quando o cliente some — motor dedicado só-leitura
+  3 etapas (cada ≥5 min, **soma ≤1380 min = 23h**, não 24h) quando o cliente some — motor dedicado
+  só-leitura. O teto é 1380 porque a janela de 24h do WhatsApp conta da **mensagem do cliente**, não do
+  primeiro follow-up; somar 1440 é recusado com 422 (e no campo legado `follow_up_time` a mensagem de
+  erro ainda diz "1440" por engano — o teto aplicado é 1380)
 - `config.follow_up_skip_conditions`: array (até 3, lógica OU) de condições pra NÃO fazer follow-up.
   Tipos: `label`, `contact_attr`/`conversation_attr`, e `time_window` (horário de silêncio: `start`/`end`
   horas 0-23, janela circular — no período não envia follow-up, mas a IA segue respondendo o cliente)
@@ -223,8 +226,12 @@ os de `user_ids` viram membros comuns. A resposta traz `is_supervisor` (boolean)
   com 422 "step 1 must be at least 5 minutes"). `feature_pause_on_human_reply`,
   `feature_follow_up` e demais booleans de config aceitam update direto via
   `captain_assistants_update` (merge parcial de config).
-- `config.feature_pause_on_human_reply`: bool — a IA se desliga sozinha na conversa quando um humano
-  assume (atendente responde pelo painel OU mensagem do celular); nota privada/automação/campanha não contam
+- `config.feature_pause_on_human_reply`: bool (nasce desligado) — a IA se desliga sozinha na conversa
+  quando um humano assume (atendente responde pelo painel OU mensagem do celular); nota
+  privada/automação/campanha não contam. **Mensagem agendada depende de quem agendou (2026-07-29):**
+  agendada **pela IA** não desliga (o disparo assina como o assistente); agendada **por um atendente**
+  conta como atendente ao vivo e **DESLIGA** a IA da conversa — na prática, programar uma mensagem em
+  nome do atendente numa conversa com IA ativa tira a IA dali quando ela for enviada
 - `config.model`: modelo OpenAI usado (gpt-4o, gpt-4o-mini)
 - `config.temperature`: 0.0-1.0
 - `config.instructions`: prompt sistema (Liquid template, até 20.000 chars)
@@ -373,16 +380,23 @@ Campos MUTÁVEIS (atualizáveis livremente por IA/integração): `marital_status
 
 `custom_attribute_definitions` (model=`contact_attribute`) fica reservado a dado de NEGÓCIO genérico que não tem modelo dedicado (ex: "plano contratado", "nicho do cliente").
 
-## Ligações — TRÊS sistemas distintos (não confundir!)
+## Ligações — CINCO sistemas distintos (não confundir!)
 
 | Sistema | O que é | Tools | Canal |
 |---|---|---|---|
-| **Ligação WP (Wavoip)** | Voz pelo WhatsApp em caixa **QR Code/WAHA** — QR conecta um "device" Wavoip; widget de discagem, gravação e transcrição automática | **NENHUMA — sem tool no MCP** (ver nota abaixo) | WhatsApp QR Code |
+| **Ligação WP (Wavoip)** | Voz pelo WhatsApp em caixa **QR Code/WAHA** — QR conecta um "device" Wavoip (pago, por caixa); widget de discagem, gravação e transcrição automática | **NENHUMA — sem tool no MCP** (ver nota abaixo) | WhatsApp QR Code |
+| **LionCalls** | Voz pelo WhatsApp em caixa **QR Code**, mas pelo **motor próprio do LionChat** (credencial global, 1 sessão por caixa; flag `lioncalls_calling`, nasce desligada e é ligada conta a conta) | **NENHUMA — sem tool no MCP** | WhatsApp QR Code |
 | **WhatsApp Calling (Cloud)** | Voz pelo WhatsApp na **API oficial** (enterprise) | `whatsapp_calls_*` + enable/disable_whatsapp_calling | WhatsApp oficial |
-| **VoIP (Zenvia)** | Telefonia COMUM (ramais, saldo, recarga) | `voip_*` | Telefone |
+| **VoIP (Zenvia)** | Telefonia COMUM com softphone no navegador (ramais, saldo, recarga) | `voip_*` | Telefone |
+| **VTCall** | Telefonia por **PABX click-to-call**, config por conta + ramal por atendente; **sem softphone no navegador** — o atendente fala pelo app/ramal do VTCall | `vtcall_settings_*` (show/update/test_connection), `vtcall_ramals_*` (list/create/destroy) | Telefone (PABX do cliente) |
 
-Quando o usuário falar "ligação", descubra o canal: caixa QR Code → Wavoip; caixa oficial →
-whatsapp_calls; telefone fixo/ramal → VoIP Zenvia.
+Quando o usuário falar "ligação", descubra o canal ANTES de responder: caixa QR Code → Wavoip **ou**
+LionCalls (dois motores diferentes para o MESMO tipo de caixa — veja qual está conectado nela); caixa
+oficial → `whatsapp_calls`; telefone/ramal → Zenvia (softphone) ou VTCall (PABX).
+
+**Histórico é compartilhado.** Wavoip, LionCalls, Zenvia e VTCall gravam na MESMA tabela de ligações,
+então `voip_calls_list` (`/voip/calls`) devolve as quatro juntas — mesmo as que não têm tool própria.
+Só o WhatsApp Calling (Cloud) fica fora, em `whatsapp_calls_*`.
 
 **Wavoip — SEM TOOL NO MCP (decisão do dono, 2026-07-16).** As 8 tools `wavoip_*` (status, token,
 calls, connect, disconnect, settings, should_ring, flag_rejected) foram REMOVIDAS dos dois conectores.