@lionchat/mcp-server 1.15.0 → 1.16.0

package/dist/docs/resources/glossary.md

@@ -74,6 +74,15 @@ Glossário completo de termos, status codes, enums e conceitos da plataforma. Us
   de WhatsApp — oficial e QR Code). A bolha mostra o selo "Encaminhada"
 - `content_attributes.frequently_forwarded`: `true` = encaminhada MUITAS vezes (o "encaminhada com
   frequência" do WhatsApp). Útil pra responder "essa mensagem foi encaminhada?" sem chutar
+- `content_attributes.edited`: `true` = o CLIENTE editou a mensagem no WhatsApp (`edited_at` traz
+  quando). O `content` já é o texto novo; a versão anterior não fica guardada. Vale nos dois canais
+  de WhatsApp (QR Code desde 18/07/2026; oficial desde 21/08/2026 — entra com o próximo deploy do
+  app depois de 21/08/2026; antes a edição virava um balão VAZIO novo, contado como mensagem nova).
+- `content_attributes.deleted`: `true` = mensagem APAGADA ("apagar para todos"), pelo cliente ou
+  pela empresa no celular (convivência). O `content` vira `"⛔ Esta mensagem foi excluída"` seguido
+  do texto original (a equipe continua vendo o que foi dito); os anexos são removidos. Ao resumir
+  uma conversa, trate como apagada — não cite o texto como se ainda estivesse de pé. (No canal
+  oficial, desde 21/08/2026 — entra com o próximo deploy do app depois de 21/08/2026.)
 
 ## Attachment (Anexo)
 
@@ -296,6 +305,18 @@ comportamento intencional.
 - `role`: `agent` (atendente) ou `administrator` (admin/dono)
 - `availability`: `online`, `busy`, `offline`
 - `permissions`: array de strings com permissões granulares
+- `replacing`: `true` em `lionchat_agents_list` por até 30 min enquanto uma substituição
+  (`lionchat_agents_replace`) transfere a carteira desse agente pro novo — ele está SAINDO; não
+  atribua nada a ele
+
+### Agente de SUPORTE (SupportAccessGrant) — não é agente da conta
+
+Quem entra na conta por **acesso de suporte** (operador da plataforma) aparece como administrador,
+mas **não é membro da equipe**: `lionchat_agents_list` não o lista (escopo `regular_users`), ele
+não ocupa vaga do plano, não pode ser substituído (`agents_replace` recusa) e, desde 17/08/2026,
+a IA também o ignora — não atribui conversa a ele, não agenda mensagem no nome dele, não o menciona
+em alerta nem o conta como "disponível". Exceção deliberada: se alguém o atribuir à mão como
+responsável, ele segue valendo como responsável.
 
 ## AutomationRule (Regra de automação)
 
@@ -309,7 +330,11 @@ comportamento intencional.
 - `booking_event_type_id`: FK pro tipo de evento (ex: "Demo 30min")
 - `attendee_email`, `attendee_name`, `attendee_phone`
 - `start_time`, `end_time`: ISO 8601
-- `status`: `scheduled`, `cancelled`, `completed`
+- `status`: `confirmed`, `cancelled`, `completed` — mas **só muda quando o cancelamento/conclusão
+  vem pelo link do paciente ou pela IA**. Quem conclui/cancela pela Agenda mexe na TAREFA
+  (`account_tasks.status`: `pending`/`completed`/`cancelled`/`snoozed`), e o booking fica
+  `confirmed`. Pra saber se um agendamento aconteceu, leia a tarefa (`lionchat_tasks_show`), não o
+  booking.
 
 **A IA agenda EXCLUSIVAMENTE por agenda de Booking (15/08/2026).** Não existe mais agendamento
 avulso/direto pela IA — ela consulta as agendas liberadas, respeita os dias em que a agenda não

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

@@ -48,6 +48,17 @@ Stages NÃO são tabela separada. São armazenadas como jsonb dentro do Funnel:
 }
 ```
 
+**Etapa que não existe no funil (desde 19/08/2026):**
+- `kanban_items_create`/`_update`/`_move` com `funnel_stage` que o funil não tem **não falha e não
+  some**: o card é REDIRECIONADO — pro destino gravado quando a etapa foi apagada, senão pra etapa
+  da mesma posição, senão pra primeira. **Confira o `funnel_stage` da resposta**: pode ser diferente
+  do que você mandou. Leia `funnels_show` antes e use o slug exato.
+- `funnels_update` que tira do `stages` uma etapa com card responde **422 `STAGE_HAS_ITEMS`** com
+  `stages: {"<slug>": <quantos cards>}`. Primeiro mova os cards com `lionchat_funnels_create_2`
+  (`POST /funnels/{id}/migrate_stage`, `from_stage`, `to_stage` ou `to_funnel_id`) e só então
+  reenvie o funil sem a etapa. Não existe parâmetro de destino no `update` de propósito.
+- Funil apagado continua sendo erro (o card não é criado).
+
 ### KanbanConfig (Configuração Global do Kanban) — CRÍTICO
 
 **Tabela separada do Funnel.** 1:1 com a conta. Guarda configurações que valem pra TODOS os funis. Tem 5 campos jsonb importantes:
@@ -245,6 +256,11 @@ Log automático de eventos do card:
 
 Tipos comuns: `created`, `stage_changed`, `agent_assigned`, `agent_removed`, `note_added`, `value_changed`, `priority_changed`, `archived`.
 
+Quem fez: `by_user_id`/`user` traz a pessoa; ação de automação ou flow vem com o nome da regra/fluxo;
+ação da IA (desde 21/08/2026 — entra com o próximo deploy do app depois de 21/08/2026) vem como
+`"IA: <nome do assistente>"` com `id` nulo — antes saía sem autor. Ao explicar um histórico de card,
+use esse campo pra dizer se foi gente, automação ou IA.
+
 ## Checklist (tarefas dentro do card)
 
 Array plano de itens. Cada item pode (opcionalmente) pertencer a um grupo via `group_id` +
@@ -580,7 +596,9 @@ Cada card pode receber atributos custom de 3 origens diferentes. **A escolha do
 ## Diagnóstico: "Card sumiu do funil"
 
 1. Está arquivado? `archived = true` em algum nível?
-2. Etapa atual existe ainda? (etapa removida do funil deixa card "órfão")
+2. Etapa atual existe ainda? Desde 19/08/2026 card em etapa inexistente é redirecionado na
+   gravação (e os 621 antigos foram movidos pra primeira etapa) — se ainda sumiu, filtre por
+   `funnel_stage` com o slug que aparece em `kanban_items_show` e compare com `funnels_show`.
 3. `position` está faltando? (cards sem position vão pro fim)
 4. Está em outro funil? (mover entre funis muda `funnel_id`)
 

package/dist/docs/resources/reports-guide.md

@@ -153,6 +153,7 @@ conversa antiga que NÃO aparece no relatório de hoje (régua antiga por criaç
 | "retrospectiva do ano" | `lionchat_reports_list_15` |
 | "satisfação", "CSAT", "nota dos clientes" | `lionchat_csat_metrics` |
 | "SLA", "cumprimento de prazo" (se a conta tiver Enterprise) | `lionchat_sla_metrics` |
+| "quantos agendamentos", "taxa de comparecimento", "agendamentos por tipo/atendente" | `lionchat_booking_reports` (ver "Agendamentos" no fim deste guia) |
 
 ---
 
@@ -330,6 +331,11 @@ Retorna:
 
 **Filtros aceitos (expostos na tool desde 2026-07-24):** `inbox_id`, `team_id`, `sla_policy_id`, `label_list[]`, `assigned_agent_id`, `since`/`until` (unix segundos).
 
+Latência de detecção: o prazo é conferido a cada 5 min, e desde 21/08/2026 (entra com o próximo
+deploy do app depois de 21/08/2026) as conferências saem espalhadas em até 2 min dentro do ciclo —
+um estouro pode aparecer em `sla_list`/`sla_metrics` até ~7 min depois do horário-limite. Não é
+defeito; não conclua "o SLA não está rodando" por isso.
+
 ## Padrões de interpretação
 
 ### Comparando períodos
@@ -555,7 +561,7 @@ nenhum `reports_*` responde; aqui é `funnel_stages` + `date_basis: closed` + `s
 
 Não é consulta livre: escolha um `widget_type` e preencha **só os campos daquele tipo**.
 
-### Os 7 tipos de bloco
+### Os 9 tipos de bloco
 
 | Tipo | Campos | Recurso exigido |
 |---|---|---|
@@ -563,13 +569,26 @@ Não é consulta livre: escolha um `widget_type` e preencha **só os campos daqu
 | `entity_ranking` | `dimension` (agent/inbox/team/label) · `metric` (conversations, resolutions, avg_first_response_time, avg_resolution_time) · `time_range` | — |
 | `csat_summary` | `time_range` | — |
 | `sla_summary` | `time_range` | `sla` (Enterprise) |
-| `funnel_stages` | `funnel_id` · `date_basis` (created/moved/closed/any) · `status` (all/open/won/lost) · `time_range` | `kanban_board` |
+| `funnel_stages` | `funnel_id` · `date_basis` (created/moved/closed/any) · `status` (all/open/won/lost) · `measure` (count padrão / value = soma do valor dos cards) · `time_range` | `kanban_board` |
+| `stage_entries` | `funnel_id` · `measure` (count/value) · `time_range` — quantos cards DISTINTOS ENTRARAM em cada etapa no período (histórico desde 12/07/2026) | `kanban_board` |
+| `calls_report` | `dimension` (agent/inbox) · `time_range` — ligações / atendidas / não atendidas / não concluídas / tempo total / tempo médio | — |
 | `lead_origin` | `time_range` | `liontrack` |
 | `agent_report` | `dimension` (agent/team/inbox) · `scope_type`+`scope_id` · `columns[]` · `time_range` | — |
 
-**`time_range`:** `last_7_days`, `last_30_days`, `this_month`, `last_month` — e `custom` **só em
-`conversations_timeseries` e `agent_report`**, exigindo `from`/`to`. **A janela não pode passar de 92
-dias**, e esse teto é da janela, não de um tipo: pedir "esse ano" é recusado com a explicação.
+`stage_entries`, `calls_report`, `measure`, `today`/`yesterday` e os metadados `title`/`width`/`height`
+são commits de 21/08/2026 (entram com o próximo deploy do app depois de 21/08/2026); `custom` em
+todos os tipos está no ar desde 19/08/2026.
+
+**`time_range`:** `today`, `yesterday` (desde 21/08 — o menor período era 7 dias), `last_7_days`,
+`last_30_days`, `this_month`, `last_month` e `custom` (com `from`/`to`, **em qualquer tipo** desde
+19/08/2026). **A janela `custom` não pode passar de 92 dias** — o teto é da janela, não do tipo;
+"esse ano" é recusado com a explicação. `today`/`yesterday` resolvem no fuso do `timezone_offset`
+enviado — mande o da conta.
+
+**Metadados do bloco (irmãos de `widget_type`, fora dos params):** `title` (nome que a pessoa dá ao
+bloco, até 80 caracteres; vazio = o painel mostra o rótulo do tipo), `width` (1 a 4 colunas; padrão
+2) e `height` (`normal` | `tall`). Preencha `title` em todo bloco que você criar — quatro blocos de
+funil sem nome chegam indistinguíveis pra quem lê depois.
 
 **Colunas do `agent_report`:** `leads`, `atendidos`, `resolvidas`, `abertas`, `pendentes`, `adiadas`,
 `label_count` (exige `label_id`) e `conversao` (exige `denominator` e `numerator`, que é **lista de
@@ -591,8 +610,9 @@ IDs de etiqueta**, nunca nome de métrica).
    equipe/caixa". Confundir troca a conta inteira.
 2. **Campo fora da lista é descartado em silêncio.** Se um valor "não fez efeito", provavelmente o
    nome do campo está errado.
-3. **Sempre envie `timezone_offset` em HORAS** (Brasília = `-3`). Sem ele o cálculo é em UTC e o
-   número não bate com o que o cliente vê na tela.
+3. **Sempre envie `timezone_offset` em HORAS, derivado do fuso DA CONTA** (`account_show.timezone`;
+   Brasília = `-3`, Cuiabá/Campo Grande/Manaus = `-4`). Sem ele o cálculo é em UTC e o número não
+   bate com o que o cliente vê na tela.
 4. **`update` substitui a lista de blocos inteira.** Leia com `list`, altere o array, devolva
    completo — e preserve o `id` de cada bloco que já existia.
 5. **`list` não pagina.** Se a resposta vier com aviso de corte, **não** use aquela lista para montar
@@ -669,6 +689,22 @@ Colunas: Ligações · Atendidas · Não atendidas · **Não concluídas** · Te
   Não a esconda ao resumir por pessoa.
 - A tabela lista só quem teve ligação no período — atendente ausente da tabela fez zero.
 
+### Agendamentos (`lionchat_booking_reports`) — 2026-08-19
+
+`GET /api/v2/accounts/{id}/booking_reports` — a aba Relatórios > Agendamentos. Unidade = o
+AGENDAMENTO (Booking). Params: `since`/`until` (datas; padrão 30 dias pra trás E 30 pra frente,
+porque agenda tem futuro), `event_type_id`, `user_id` (responsável da tarefa), `status`
+(`pending` | `completed` | `cancelled` | `snoozed`), `group_by` (`day` | `week` | `month`).
+Resposta: `totals` (`total`, `pending`, `completed`, `cancelled`, `snoozed`, `attendance_rate`),
+`timeline`, `by_event_type`, `by_agent`, `by_origin`.
+
+- **`attendance_rate` = concluídos / (concluídos + cancelados)**, em %. Pendentes ficam FORA do
+  denominador (ainda não aconteceram). Não recalcule com o total.
+- A SITUAÇÃO vem da tarefa da Agenda (`account_tasks.status`), não de `bookings.status` — quem
+  conclui/cancela pela Agenda deixa o booking parado em "confirmado". Ler `bookings_*` direto pra
+  contar "concluídos" dá zero.
+- `snoozed` (adiado) aparece separado de `pending` de propósito.
+
 ### Faturamento (`measure`)
 
 `measure: 'value'` faz `funnel_stages`/`stage_entries` somarem o VALOR dos cards em vez de contar.

package/dist/docs/resources/troubleshooting.md

@@ -173,7 +173,9 @@ Feature flag específica (ex: `feature_kanban`, `feature_captain`) está OFF.
 - `"private must be boolean"` — true/false, não string
 
 ### KanbanItem
-- `"funnel_stage does not exist in funnel"` — etapa inválida pro funil
+- `"STAGE_HAS_ITEMS"` (no `funnels_update`) — você tentou remover uma etapa que ainda tem card;
+  `stages` na resposta diz quantos. Mova com `migrate_stage` antes. (Card criado em etapa
+  inexistente NÃO dá erro: é redirecionado — confira o `funnel_stage` devolvido.)
 - `"conversation_display_id must exist"` — conversa não existe ou foi deletada
 - `"position must be a positive integer"` — não pode ser negativo
 
@@ -418,6 +420,18 @@ pelo painel de suporte — só volta no botão Retomar), `cancelled` (encerrada
 Enquanto uma importação está viva, o repescador de mensagens da sessão fica fora do caminho, de
 propósito. Pausar, retomar e cancelar são ações do painel de suporte — não existem no MCP.
 
+**A mídia vem DEPOIS do texto (desde 19-20/08/2026).** O import grava as conversas só com o texto
+(779 conversas em ~3 min num caso real) e busca os arquivos em segundo plano, numa fila por caixa
+com poucas vagas na instalação inteira — pode levar horas (o dono aceitou "até 24 h, contanto que
+não atrapalhe nada"). Enquanto isso a mensagem carrega `content_attributes.media_failed` com
+`retryable: true` (bolha âmbar "mídia chegando"); quando o arquivo chega, o selo some e o anexo
+aparece; se o WhatsApp já apagou o arquivo (tudo com mais de ~2 semanas), o selo vira
+`retryable: false` (vermelho, definitivo — não há repesca). `lionchat_inboxes_waha_import_status`
+responde "ainda está chegando?": `media_pending` (arquivos na fila desta caixa; 0 = tudo pedido),
+`media_swept_at`/`media_swept_count` (varredura final que recolocou órfãos na fila). `status:
+completed` com `media_pending > 0` é normal — texto pronto, fotos a caminho. Conversa de histórico
+NÃO é repescada pelo vigia de mensagens, de propósito.
+
 ### "Editei o evento no Google Calendar e não sincronizou"
 Auto-cura desde 2026-06-09: o vigia horário re-arma o "watch" morto de conexões saudáveis
 sozinho (sem reconectar a conta). Se persistir >1h, aí sim investigar a conexão
@@ -498,6 +512,15 @@ recusado; brasileiro com 55 e 12-13 dígitos é aceito mesmo no formato antigo s
 sem erro de telefone); no import do KANBAN, telefone inválido cria o card SEM contato e SEM
 conversa, em silêncio — comportamento diferente do import de contatos.
 
+**Complementos de 19/08:** telefone PREENCHIDO e inválido **recusa a linha inteira** — o contato não
+nasce (antes ele nascia mudo, sem telefone). Coluna de telefone **vazia** continua criando o contato
+(lista de nome + e-mail é uso legítimo). **Linha totalmente vazia não é erro**: é pulada e contada em
+`blank_rows` no resultado — planilha de 300 linhas com 2 preenchidas deixa de gerar 298 "Nome é
+obrigatório". Telefone em notação científica do Excel (`9,88888E+12`) recebe mensagem própria
+("formate a coluna como texto"), não "confira o DDI". No `contacts_import_validate`, o número da
+linha no relatório é a posição REAL no arquivo (linhas vazias contam na numeração, não no total
+conferido).
+
 ## "A caixa oficial parou de disparar / de receber" — avisos automáticos da Meta (18/08)
 
 Duas famílias de chaves novas em `additional_attributes` da caixa `Channel::Whatsapp`
@@ -512,6 +535,15 @@ Duas famílias de chaves novas em `additional_attributes` da caixa `Channel::Wha
   e `reauthorization_required` vira `true` SOZINHO. Com `reauthorization_required: true` a caixa
   fica MUDA (descarta o que chega) até reconectar. A ausência dessas chaves NÃO prova que a caixa
   está conectada (caixa antiga só ganha o aviso após reinscrição).
+- **Registro do número incompleto** (20/08): `whatsapp_registration_error` (texto, a frase da
+  própria Meta — ex.: verificação em duas etapas ligada num número que veio de outra plataforma).
+  A caixa foi criada e **continua recebendo**; só o registro do número não terminou. É diferente de
+  `reauthorization_required` (esse emudece a caixa). Orientação: resolver do lado da Meta e clicar
+  em "Concluir registro" na caixa; a chave some quando o registro passa. Conectar uma caixa oficial
+  é ação de administrador e respeita o teto de caixas do plano (402 antes de abrir a janela da Meta).
+- Reconectar uma caixa em convivência pelo botão volta a pedir o histórico de 180 dias sozinho
+  (19/08); é um tiro único por onboarding — se a Meta recusar fora da janela de 24 h, não há
+  repetição.
 
 ## "O filtro de etiqueta 'não está presente' mente" — NUNCA mentiu pela API
 
@@ -521,6 +553,17 @@ Se alguma anotação antiga disser que esse filtro mente por API, está errada.
 verdade nos filtros: data FIXA com `is_greater_than`/`is_less_than` passou a cortar o dia no fuso
 da CONTA (ver resource `filtros-e-relatorios`).
 
+## "Mapeei o campo da integração pro atributo da conversa e nada foi gravado" (21/08 — entra com o próximo deploy do app depois de 21/08/2026)
+
+Quatro causas, nesta ordem: (1) o evento não abriu conversa — atributo de conversa só existe na
+conversa que a automação/fluxo mapeado cria (contato sozinho não tem onde gravar); (2) a chave é
+reservada (`imported_from`, `type`, `captain_*`... — lista em `api-conventions`) e foi recusada;
+(3) o valor não é do TIPO do atributo (texto num campo de Número, data em formato estranho) e foi
+descartado — o log do servidor tem `[IntegrationAttributes] ... tipo_invalido=[...]`; (4) nos
+gateways, a chave não está em `conversation_attribute_keys` daquele evento (a granularidade é por
+evento: "compra aprovada" e "carrinho abandonado" gravam listas diferentes). Gravar por integração é
+silencioso: não espere automação nem webhook de saída reagindo ao atributo.
+
 ## Quando reportar pro suporte
 
 Reporte se:
@@ -533,3 +576,13 @@ NÃO precisa reportar:
 - 4xx (você fez algo errado)
 - Rate limit (esperado)
 - 404 de recurso deletado
+
+## Conector REMOTO "conecta e desconecta" a cada ~6 minutos (Claude Code / VS Code / Codex ligados direto)
+
+Vale SÓ para o conector remoto (`mcp.lionchat.com.br`). O conector local (npm, stdio) não tem canal de rede.
+Sintoma: `/mcp` alterna connected/disconnected a cada ~6 min; nenhuma chamada falha.
+Causa (21/08/2026): o cliente segura um canal GET esperando avisos do servidor; o Cloudflare derruba
+qualquer resposta que fique 125 s sem um byte (Proxy Read Timeout). Quem usa pela claude.ai/ChatGPT não
+abre esse canal e nunca vê isso.
+Correção (v1.15.1): o servidor manda um `ping` a cada 30 s enquanto o canal está aberto.
+Interruptor: `MCP_KEEPALIVE_INTERVAL_MS` (0 = desligado). Detalhe: `docs/plans/mcp-keepalive-cloudflare/`.