@lionchat/mcp-server 1.10.2 → 1.10.3

package/dist/docs/instructions.md

@@ -374,6 +374,9 @@ Antes de escolher a ferramenta, cheque se a intenção bate com a coluna da dire
 | **Definir supervisor** de caixa | `lionchat_inbox_members_create` / `_update` com `supervisor_ids[]` | Supervisor vê TUDO da caixa mas fica fora do rodízio (ver abaixo) |
 | **Definir supervisor** de time | `lionchat_team_members_create` / `_update` com `supervisor_ids[]` | Contrato diferente do da caixa: `user_ids[]` é a lista COMPLETA e `supervisor_ids[]` um subconjunto dela. Omitir `supervisor_ids` não mexe em papel nenhum (seção 2) |
 | **Mudar a fila do time** (teto por atendente, janela, online/offline) | `lionchat_teams_update` (`assignment_mode`, `fair_distribution_limit`, `fair_distribution_window`) | Time tem PREFERÊNCIA sobre a caixa na distribuição. Leia a config atual antes de mudar (ver `lionchat://docs/conversation-flows`) |
+| **Criar/atualizar time** | `lionchat_teams_create` / `_update` | **Preencha `description`**: desde 03/08 é ela que o AI Agente lê pra decidir o roteamento por time. Descreva QUANDO mandar pra lá, não o que o time é |
+| **Pausar a automação no meio** (esperar atribuição/card antes da próxima ação) | ação `wait` em `lionchat_automation_rules_create` / `_update` | Segundos, teto 300. Acima disso é caso de FlowBuilder. Ver `lionchat://docs/conversation-flows` |
+| **Buscar contato/conversa/card** | `lionchat_search_*`, `lionchat_contacts_search` | **Termo com letra exige 3+ caracteres** (dígito é isento). Menos que isso volta VAZIO sem erro — não conclua que o registro não existe. Ver `lionchat://docs/api-conventions` |
 | **Migrar conversas** de uma caixa WhatsApp pra outra (ex.: QR Code → Oficial) | `lionchat_inboxes_inbox_migration_list` (prévia) → `_execute` → acompanhar status | Admin-only e IRREVERSÍVEL: sempre mostre os números da prévia e confirme (seção 7a). Grupos não vão pro canal oficial — ficam na caixa de origem |
 | Qualquer coisa de Ligação WP (Wavoip) | **NÃO HÁ TOOL** — removidas em 2026-07-16 por decisão do dono | Ligação WP é contratada e configurada **manualmente pelo cliente no painel**. O MCP não conecta, não desconecta, não entrega token de discagem nem muda config. Oriente o usuário a fazer pelo painel (Configurações da caixa → Ligação WP). |
 | Restringir agendas que a IA oferece | `lionchat_captain_assistants_update` (`config.booking_event_type_ids: [Int]`) | binding de agenda por cenário NÃO é settable via API |

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

@@ -379,6 +379,29 @@ falha silenciosa, sem erro na tela. Conversa se altera por `fields` (+ `labels:
 **Multi-termo com E:** `q` aceita String (espaços = AND implícito) ou Array (`q[]=joao&q[]=silva`),
 cap de 5 termos — cada termo precisa bater (cada um mantém seu OR entre campos).
 
+**PISO DE 3 LETRAS (novo 2026-08-04) — leia antes de concluir "não existe".**
+
+Termo com LETRA precisa de **3 caracteres ou mais**. Termo **só de dígitos** é isento (é assim
+que se busca pelo número da conversa ou do card, e conta nova tem todos com 1-2 dígitos).
+
+| Busca | O que acontece |
+|---|---|
+| `q=Bo` | Devolve **vazio**. Não é erro, não é 422 — vem `payload: []` |
+| `q=Bor` | Busca normal |
+| `q=42` | Busca normal (só dígitos, isento) |
+| `q=jo silva` | Vale: basta **um** termo utilizável na frase |
+| `q=zq` + `contact_filters=[...]` | Vazio. O termo curto **invalida a busca inteira**, mesmo com filtro junto |
+
+Vale nas CINCO buscas (contato, conversa, mensagem, card e artigo).
+
+**Consequência prática:** resultado vazio com termo de 1-2 letras **não significa que o registro
+não existe** — significa que a busca não rodou. Nunca responda "não encontrei esse contato" nessa
+situação. Ou complete o termo, ou pergunte o nome inteiro, ou use `/contacts/filter` com
+`filter_operator: "contains"`, que não tem esse piso.
+
+Sem `q` e só com filtros estruturados continua funcionando normalmente (contrato antigo, busca só
+por condições) — o piso só descarta termo de texto curto, não o pedido inteiro.
+
 **Busca cadastral:** CPF/CNPJ/RG/endereço/profissão entram na busca de contatos e conversas, com
 match por dígitos que ignora pontuação (`31.104.475/0001-51` == `31104475000151`; mín 3 dígitos).
 Telefone idem. Cards do Kanban são achados pelo contato/conversa vinculados.

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

@@ -131,6 +131,32 @@ Pra reativar: `paused=false`. Toggle é auditado (`audited only: [:paused]`).
 
 O `config` DEVE ser enviado como **objeto** (ex.: `config: { disabled_tools: [...] }`), NUNCA como string/texto. Se vier em formato errado, o backend retorna **422** (não salva ignorando em silêncio). O update do `config` é **merge parcial** — mandar só o subset que muda (ex.: só `disabled_tools`) preserva os demais campos.
 
+## AI Agente roteando por TIME (novo 2026-08-03)
+
+O AI Agente ganhou 3 ferramentas de time: **Listar Times**, **Mover para Time** e **Tirar do Time**.
+Antes ele só conseguia atribuir uma PESSOA; trocar de time exigia automação ou bloco de fluxo, com
+o time escolhido de antemão por quem montou a regra.
+
+**A descrição do time virou peça funcional.** É lendo `teams.description` que a IA decide para onde
+mandar a conversa. Time sem descrição obriga a chumbar o nome no cenário — que é justamente o que
+essas ferramentas vieram resolver.
+
+> **Ao criar ou atualizar time (`lionchat_teams_create` / `_update`), preencha `description`
+> dizendo QUANDO mandar para lá.** Ex.: `"Financeiro — cobrança, boleto, nota fiscal, reembolso,
+> segunda via"`. Não é enfeite de tela: é o que a IA lê.
+
+Travas que valem conhecer (não dá pra desligar):
+
+| Trava | Efeito |
+|---|---|
+| Conta sem nenhum time | As 3 ferramentas nem aparecem para o agente |
+| Alguém está atendendo (`assignee_id` preenchido) | Mover e Tirar **não agem**. Evita a IA arrancar a conversa da mão do atendente |
+| Nome do time no cenário | Resolve por nome exato; não achando, tenta CONTÉM. Se der mais de um candidato, devolve a lista e **não adivinha** |
+| Mover de time | **Não** faz handoff sozinho. Se a intenção é o humano assumir, o cenário precisa mandar chamar o handoff no mesmo turno |
+
+`list_teams` é ferramenta de descoberta: fica escondida da tela de ferramentas e só carrega se
+"Mover para Time" estiver ativa. Não tente ligá-la ou desligá-la sozinha em `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.
@@ -502,6 +528,20 @@ opcional `variable_mapping` junto.
 - Só entram no mapping as que devem auto-preencher; as demais `{{N}}` continuam manuais.
 - O `variable_mapping` é salvo localmente (NÃO vai pra Meta) e usado no momento do envio.
 
+**Variável sem mapping tem preço (2026-08-04).** Placeholder que ninguém disse como preencher:
+
+1. **Tira o modelo do alcance do AI Agente.** Basta UMA variável sem mapping para o modelo inteiro
+   deixar de ser oferecido no follow-up automático fora da janela de 24h.
+2. **Faz o envio manual falhar** com o erro `#132000` da Meta (número de parâmetros não bate).
+
+Vale para os dois formatos de marcador: posicional (`{{1}}`) e nomeado (`{{nome_cliente}}`).
+
+> Ao registrar modelo por API, **mapeie todas as variáveis do corpo** — ou preencha na hora do envio
+> via `processed_params`. Modelo com variável órfã é modelo que a IA não usa e que o disparo derruba.
+
+Confira o que ficou de fora lendo o modelo com `lionchat_inboxes_whatsapp_templates_list` e
+comparando os `{{...}}` do texto do BODY com as chaves do `variable_mapping`.
+
 Exemplo — `{{1}}` vira o primeiro nome do contato:
 
 ```json

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

@@ -255,6 +255,33 @@ Conversa resolvida que recebe nova mensagem do cliente:
 - Default: cria NOVA conversa (mantém histórico)
 - Se locked: reabre a mesma conversa (`status` volta a 0)
 
+### 10. Criar conversa por API — REGRA NOVA (2026-08-04)
+
+**Nunca nasce conversa nova se o contato já tem uma ABERTA naquela caixa.** Vale para todo caminho
+iniciado por nós: `lionchat_conversations_create`, campanha, flow, booking, integração.
+
+| Situação do contato naquela caixa | O que `conversations_create` devolve |
+|---|---|
+| Tem conversa **aberta / pendente / adiada / silenciada** | A **conversa existente**, com o mesmo `id`. Não cria |
+| Só tem conversa **resolvida** | Cria conversa NOVA (invariante do produto: "fechou = abre nova") |
+| Caixa com `lock_to_single_conversation` LIGADO | **Sempre** a existente, mesmo resolvida — reabre |
+| Caixa de **e-mail** | Sempre cria nova (o assunto da thread vem da conversa; reusar mandaria o e-mail com o assunto velho) |
+
+**Como saber se reusou:** compare o `id` devolvido com o que você esperava. Vem HTTP 200 nos dois
+casos, sem aviso. Se precisa garantir conversa nova, feche a anterior antes
+(`conversations_toggle_status` para `resolved`).
+
+**O que é DESCARTADO no reuso** (a conversa já existe; o disparo não reescreve o estado dela):
+`status`, `snoozed_until`, `additional_attributes` e `assignee_id`. Se você precisa trocar o
+responsável, chame `conversations_update` depois — não adianta mandar junto na criação.
+
+**O que É aproveitado:** `custom_attributes` entram por merge, **sem sobrescrever chave que já tem
+valor**. A conversa mantém a origem com que nasceu e só ganha o que ainda não tinha.
+
+**Reuso não dispara `conversation_created`** — automação, gatilho de flow, webhook de saída,
+notificação e a Agenda não rodam. Se o seu fluxo depende de um desses, ele não vai acontecer
+quando houver reuso.
+
 ## Estado relacional
 
 ```
@@ -634,10 +661,41 @@ Todos os formatos abaixo foram conferidos linha a linha em `app/services/action_
 | `add_note_to_kanban_item` | `[{"funnel_id": 31, "text": "texto da nota"}]` — a chave e **`text`**, nao `note` |
 | `set_kanban_item_status` | `[{"funnel_id": 31, "status": "won"}]` — `won`, `lost` ou `open`. Status fora disso e ignorado |
 | `start_kanban_item_timer` / `stop_kanban_item_timer` | `[{"funnel_id": 31}]` |
+| `wait` | `[30]` — segundos. Ver "Acao Aguardar" abaixo |
 
 **Acoes de Kanban:** todas precisam que a conversa ja tenha um card no funil informado. Sem card,
 a acao e pulada (fica so no log do servidor). Use `create_kanban_item` antes, na mesma regra.
 
+### Acao `wait` (Aguardar) — novo 2026-08-04
+
+Pausa a regra: as acoes **seguintes** so rodam depois do tempo passar. As anteriores ja rodaram.
+
+```json
+{ "action_name": "wait", "action_params": [30] }
+```
+
+| Regra | Detalhe |
+|---|---|
+| Unidade | **segundos** |
+| Teto | **300** (5 minutos). Valor maior e limitado a 300 em silencio, sem erro |
+| Formatos aceitos | `[30]`, `30`, `"30"` e `{"seconds": 30}` — todos funcionam |
+| Tempo invalido | `[]`, `[0]`, `[""]` ou ausente = **nao pausa**, a regra segue direto. Nao da erro |
+| Ultima acao da regra | Nao agenda nada (nao ha o que retomar depois) |
+| Pilula "Automacao X disparou" | So aparece na 1a rodada, nao se repete na volta |
+
+**Para que serve.** O caso que originou: a regra mandava a mensagem **antes** da politica de
+atribuicao carimbar o responsavel, entao a variavel com o nome do atendente saia vazia. Meio
+segundo de espera resolve. Use quando a acao seguinte depende de algo que outro processo ainda
+esta gravando (atribuicao, card recem-criado, atributo que outra regra vai escrever).
+
+**Precisa de mais de 5 minutos?** O lugar certo e o FlowBuilder, que tem espera em horas e sessao
+propria pra sustentar o estado. A automacao nao foi feita pra isso.
+
+**A regra nao "dorme":** ao encontrar a espera ela encerra a rodada e agenda a retomada. Varias
+conversas esperam ao mesmo tempo sem travar o atendimento. Na volta, o sistema confere se a regra
+ainda existe e esta ligada, se a conversa ainda existe e se a caixa nao foi excluida — se algo
+disso mudou, ele simplesmente nao retoma.
+
 Lista autoritativa de nomes validos: `AutomationRule#actions_attributes` no backend. Nome de acao
 fora dessa lista e recusado com 422 ao salvar — isso a API valida. O que ela **nao** valida e o
 conteudo do `action_params`. `apply_kanban_checklist_template` existe no motor mas **nao** e uma

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

@@ -412,14 +412,25 @@ Atributos de sistema no CONTATO (prefixo `eclinica_`, protegidos, usáveis como
 | `eclinica_idagenda` | text | ID do último agendamento |
 | `eclinica_data_consulta` | date | Data da consulta, ISO |
 | `eclinica_hora_consulta` | **time** | Hora da consulta 24h `"HH:MM"` (novo 2026-07-06) |
+| `eclinica_hora_final` | **time** | Hora final da consulta (novo 2026-07-27) |
 | `eclinica_status_agendamento` | text | agendado / no_show / atendido / desmarcado |
-| `eclinica_compromisso` | text | Tipo da consulta (ex: Consulta, Retorno, Exame) |
+| `eclinica_situacao` | text | Situação crua da agenda (age_situacao do webhook) |
+| `eclinica_compromisso` | text | Tipo da consulta — TEXTO LIVRE da recepção (ex: Consulta, Retorno) |
+| `eclinica_agendatipo` | text | Tipo de Agendamento — NOME da lista fixa do painel, resolvido por unidade (novo 2026-07-28). **Filtrar sempre pelo NOME, nunca pelo número: os números colidem entre filiais** |
+| `eclinica_agendatipo_id` | text | Tipo de Agendamento — número cru (não comparável entre filiais) |
+| `eclinica_profissional` | text | NOME do profissional, resolvido por unidade (novo 2026-07-10) |
+| `eclinica_profissional_id` | text | Número do profissional (não comparável entre filiais) |
+| `eclinica_convenio_id` | text | Convênio (número) |
+| `eclinica_ultimo_evento` | text | Tipo do último webhook recebido (ex: falta, agendamento_novo) |
 | `eclinica_ultimo_pagamento` | text | Valor do último pagamento |
 | `eclinica_ultimo_pagamento_data` | date | Data do último pagamento/baixa (novo 2026-07-06) |
 | `eclinica_ultimo_pagamento_descricao` | text | Descrição da baixa (ex: CONSULTA INICIAL) |
 | `eclinica_laboratorio_data_prevista` | date | Previsão de entrega da medicação (novo 2026-07-23) |
 | `eclinica_laboratorio_data_moldagem` | date | Data do pedido da medicação |
-| `eclinica_laboratorio_data_entrega` | date | Data de entrega da medicação |
+| `eclinica_laboratorio_data_entrega` | date | Data em que a medicação CHEGOU na unidade — é a data que dispara o aviso de retirada do flow |
+| `eclinica_laboratorio_data_retirada` | date | Data em que o paciente RETIROU a medicação (coa_datainstalacao; novo 2026-08-03). NÃO confundir com a entrega. Vazia = peça atual não retirada |
+| `eclinica_laboratorio_trabalho_id` | text | Trabalho/tipo da medicação — número cru (aparelho_id; novo 2026-08-03). Lista própria de cada unidade (COMPRIMIDO/POMADA/SPRAY...); número não comparável entre filiais |
+| `eclinica_laboratorio_trabalho` | text | Trabalho/tipo da medicação — NOME resolvido na lista da própria unidade ("SPRAY", "POMADA"...; novo 2026-08-03). Best-effort: pode ficar vazio se a API da unidade estiver fora do ar. Para filtrar/personalizar flows, use SEMPRE este NOME, nunca o número |
 | `eclinica_laboratorio_situacao` | text | Situação do pedido no laboratório |
 | `eclinica_ultima_cobranca_valor` | text | Valor da última cobrança/carnê gerado |
 | `eclinica_ultima_cobranca_vencimento` | date | Vencimento da última cobrança |

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

@@ -115,7 +115,8 @@ Um card individual dentro de uma etapa.
 | `funnel_stage` | Chave da etapa (ex: `"novo_lead"`) |
 | `position` | Ordem dentro da etapa |
 | `stage_entered_at` | Quando entrou na etapa atual (pra métrica de tempo) |
-| `conversation_display_id` | Conversa principal vinculada |
+| `conversation_display_id` | Conversa principal vinculada. **O sistema move este ponteiro sozinho (desde 04/08/2026)**: quando nasce uma conversa nova do mesmo contato naquela caixa, o card passa a apontar pra ela. O card é da PESSOA, não do atendimento. **NÃO trate este valor como estável** — releia antes de usar. Enviar `conversation_display_id` num UPDATE de card é ignorado de propósito (senão o reenvio do formulário regravaria o número antigo por cima). |
+| `origin_conversation_display_id` | Conversa em que o card NASCEU (só preenchida se o vínculo já foi movido). É o que o relatório de origem de lead usa, pra uma venda não mudar de mês nem de anúncio quando o card anda. |
 | `linked_conversations` | jsonb array `[{display_id: 123}, {display_id: 456}]` — múltiplas conversas |
 | `item_details` | jsonb (ver abaixo) |
 | `custom_attributes` | jsonb — campos custom (igual contatos) |

package/dist/docs/resources/troubleshooting.md

@@ -179,6 +179,61 @@ Feature flag específica (ex: `feature_kanban`, `feature_captain`) está OFF.
 
 ## Cenários problemáticos
 
+### "A busca não acha o contato, mas ele existe" (novo 2026-08-04)
+
+Primeira coisa a conferir: **o termo tem menos de 3 letras?** Desde 04/08 termo com letra precisa
+de 3 caracteres; abaixo disso a busca é recusada e volta **vazia, sem erro**. Termo só de dígitos
+é isento.
+
+```
+q=Bo   -> payload: []   (recusado, NÃO significa que não existe)
+q=Bor  -> busca normal
+q=42   -> busca normal (dígito é isento)
+```
+
+Vale nas cinco buscas: contato, conversa, mensagem, card e artigo. Um termo curto **invalida a
+busca inteira**, mesmo com filtro estruturado junto.
+
+O que fazer: complete o termo, peça o nome inteiro, ou use `lionchat_contacts_filter` com
+`filter_operator: "contains"` — o `/filter` não tem esse piso.
+
+**Nunca responda "esse contato não existe" a partir de uma busca de 1-2 letras.**
+
+### "Criei uma conversa e voltou o id de uma que já existia" (novo 2026-08-04)
+
+É o comportamento novo, não é defeito. Desde 04/08 não nasce conversa nova se o contato já tem uma
+**aberta** naquela caixa — o sistema devolve a existente, com HTTP 200 e sem aviso.
+
+- Contato com conversa aberta/pendente/adiada/silenciada → devolve a existente
+- Só conversa resolvida → cria nova
+- Caixa com "conversa única" ligada → sempre a existente, mesmo resolvida
+- Caixa de e-mail → sempre cria nova
+
+Se você PRECISA de conversa nova, feche a anterior antes (`conversations_toggle_status` para
+`resolved`). E lembre: no reuso, `assignee_id` e `status` mandados na criação são **descartados** —
+troque depois com `conversations_update`.
+
+### "Token de cargo restrito passou a receber 403 em conversa que antes abria" (novo 2026-08-04)
+
+Mudança de segurança, não é defeito. Até 04/08 as ações de conversa autorizavam a **CAIXA**, não a
+**conversa** — então qualquer membro da caixa conseguia agir numa conversa que nem consegue abrir.
+As 19 ações do controller de conversa agora conferem a conversa.
+
+Na prática, com token de cargo restrito:
+
+| Ação | Antes | Agora |
+|---|---|---|
+| `conversations_transcript` (mandar a conversa por e-mail) | Passava em qualquer conversa da caixa | Só nas que o cargo enxerga |
+| Anexos e download do áudio | Idem | Idem |
+| Resolver/reabrir, prioridade, silenciar, marcar não-lida, atributos | Idem | Idem |
+| `conversations_scheduled_messages_list` / `_create` | **Sem autorização nenhuma** | Confere a conversa |
+
+Dois acessos continuam valendo de propósito: conversa **órfã** (cuja caixa foi apagada) é de toda a
+conta, e quem tem o **card do Kanban** enxerga a conversa vinculada mesmo sem ser membro da caixa.
+
+Se o seu fluxo dependia do comportamento antigo, o caminho é dar acesso à caixa/time certo ao cargo
+— não existe como pedir exceção pela API.
+
 ### "Estou recebendo 401 mesmo com token correto"
 Possíveis causas:
 - Token foi revogado