@lionchat/mcp-server 1.7.0 → 1.8.1

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

@@ -44,7 +44,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 |
+| `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 |
 | `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 |
@@ -59,6 +59,16 @@ Mesmo shape de condição. 15/página.
   do Kanban vinculado.
 - Condição com `custom_attribute_type:'conversation_attribute'` — atributo da conversa vinculada.
 
+### Duas regras que enganam nos filtros
+
+- **Vários valores na mesma condição** (ex.: cidade é "Sorocaba" OU "Campinas"): em CONTATOS isso só
+  passou a valer na atualização de 26/07/2026 — em instalação anterior o filtro usa só o PRIMEIRO
+  valor e descarta o resto em silêncio. Conversa sempre usou todos. Na dúvida, faça uma consulta por
+  valor e some.
+- **"Entre duas datas" não existe como operador** — são duas condições (`is_greater_than` +
+  `is_less_than`), e as duas pontas ficam **de fora**. Pra incluir os dias 01 e 10, peça de 30/06 a
+  11/07. O corte do dia é em UTC, então conversa do fim da noite conta no dia seguinte.
+
 ## 3. Kanban — `lionchat_kanban_items_filter` (lista rica de cards)
 
 GET com parâmetros FLAT (não usa payload). Filtros REAIS (2026-07-24 — parâmetros fantasmas
@@ -126,6 +136,11 @@ payload=[
 **R3 — Ganhos do mês por agente/time:**
 `kanban_items_list_3 funnel_id=37 from=2026-07-01 to=2026-07-31 user_ids=[6,12]` (ou `team_id=3`)
 
+> ⚠️ **`from`/`to` deste relatório: mande SEMPRE timestamp UNIX.** Data por extenso (`2026-07-01`)
+> só é aceita a partir da atualização de 26/07/2026; antes dela o relatório volta **inteiro zerado,
+> sem erro nenhum** (vira 1970 por dentro). Timestamp funciona em qualquer versão — use ele e você
+> nunca cai na armadilha. Se vier tudo zero e o funil tem cards, era isso.
+
 **R4 — Conversas de uma campanha que FALHARAM/entregaram:** filtre por
 `campaign_id equal_to <id>`; o status da MENSAGEM de template (sent/delivered/read/failed) está
 nas mensagens da conversa (`conversations_messages_list`) — não é atributo da conversa.

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

@@ -32,6 +32,38 @@ Quando o usuário disser "o relatório está errado / não bate", quase sempre
    Diferenças de ~1% entre relatório e lista filtrada são borda de janela/fuso, não defeito.
 6. **since/until são unix SEGUNDOS** em TODOS os endpoints de relatório. ISO 8601 quebra a janela em
    silêncio (relatório vazio/errado).
+7. **Mande SEMPRE as DUAS pontas do período.** Mandar só `since` (ou só `until`) fazia o filtro de
+   data ser ignorado por inteiro, em silêncio: vinham os números da vida toda rotulados como do
+   período pedido. Corrigido em 2026-07-25 (meia janela virou período aberto de um lado), mas a
+   recomendação continua: mande as duas.
+8. **"Não atendidas" NÃO é "nunca foi respondida".** A regra real é: **o cliente falou por último e
+   ninguém respondeu ainda**. A definição antiga ("sem primeira resposta") foi abandonada de
+   propósito, porque marcava como não atendida a conversa em que o robô/atendente falou primeiro e o
+   cliente nunca respondeu. Numa conta real as duas leituras dão 32 contra 17 — nunca explique esse
+   número como "N pessoas nunca foram respondidas".
+9. **Relatório ao vivo e `conversations_meta` NÃO contam o mesmo universo.** O ao vivo conta tudo da
+   conta, inclusive conversa de caixa apagada, e não checa permissão; o `meta` exclui caixa apagada,
+   exige contato vivo e respeita as caixas que o usuário enxerga. Podem divergir com razão.
+
+### Cinco números que estavam ERRADOS — corrigidos na atualização de 26/07/2026
+
+Achados numa validação de cada resposta contra o banco de produção. **A correção é do sistema, não
+do conector: se a instalação do cliente ainda não recebeu essa atualização, o comportamento ANTIGO
+continua valendo.** A coluna "antes" serve pra você reconhecer e avisar o usuário em vez de repetir
+um número errado com confiança.
+
+| Relatório | Antes (errado) | Depois |
+|---|---|---|
+| Por CANAL | Conversa **silenciada** não era contada: sumia do canal e do total, e a soma dos canais nunca fechava com o total do resumo (numa conta: Instagram 46 tendo 58) | Silenciada entra; a soma fecha |
+| Tempo médio por ETIQUETA | Calculado **sem janela de data**: a mesma linha dizia "37 resolvidas" e mostrava a média de 6; pedir mês fechado do passado trazia resolução ocorrida DEPOIS. Sempre pra baixo — 1,7 dia no lugar de 43,6 (**25x**) | Usa a janela do evento, como agente/caixa/time |
+| Etiqueta sem dado | Mostrava "0s" (lia como resolução instantânea) | Vem vazio |
+| Receita/ganhos do KANBAN | Venda fechada no período de card criado ANTES dele não contava (numa conta: metade dos ganhos e R$ 3.750 fora) | Conta tudo |
+| "Pendentes" do relatório ao vivo | **Sempre 0**, por condição impossível | Número real |
+| Cumprimento de prazo (SLA) | "100%" para conta com ZERO prazo aplicado — escondia "o SLA não está rodando" | Vazio = sem dados |
+
+**Como reconhecer instalação antiga:** soma dos canais menor que o total do resumo; tempo médio por
+etiqueta absurdamente baixo perto do tempo por atendente; "pendentes" zerado no ao vivo tendo
+conversa pendente na lista; "100%" de prazo com nenhum prazo aplicado.
 
 ## Mapeamento dos endpoints `lionchat_reports_*`
 

package/endpoints.json

@@ -3824,7 +3824,7 @@
     "method": "GET",
     "path": "/api/v1/accounts/{account_id}/kanban_items/reports",
     "title": "Relatório Agregado do Kanban",
-    "description": "RELATORIO AGREGADO do Kanban (funil de vendas) — a resposta e um OBJETO de metricas, nao lista de cards: soma de valores GANHOS no periodo, contagem/valor por etapa, previsao ponderada (forecast), top negocios, cards parados (stale) e metas do funil. Filtra por periodo (from/to), agentes (user_ids[]) e time (team_id). USE ESTA TOOL quando pedirem 'relatorio do funil/vendas/ganhos do mes por agente ou time'. Pra LISTAR os cards em si, use lionchat_kanban_items_filter.",
+    "description": "RELATORIO AGREGADO do Kanban (funil de vendas) — a resposta e um OBJETO de metricas, nao lista de cards: soma de valores GANHOS no periodo, contagem/valor por etapa, previsao ponderada (forecast), top negocios, cards parados (stale) e metas do funil. Filtra por periodo (from/to), agentes (user_ids[]) e time (team_id). USE ESTA TOOL quando pedirem 'relatorio do funil/vendas/ganhos do mes por agente ou time'. Pra LISTAR os cards em si, use lionchat_kanban_items_filter. ATENCAO wonInPeriod/wonValueInPeriod: em instalacao ANTERIOR a atualizacao de 26/07/2026 eles SUBCONTAM — negocio ganho no periodo cujo card foi criado ANTES do periodo fica de fora (numa conta real, metade dos ganhos e R$3.750 sumiam). Ao responder receita nessas contas, avise que o numero pode estar subestimado em funil de ciclo longo.",
     "category": "Itens",
     "params": [
       {
@@ -3839,14 +3839,14 @@
         "type": "string",
         "location": "query",
         "required": false,
-        "description": "Inicio do periodo (YYYY-MM-DD ou ISO 8601)"
+        "description": "Inicio do periodo — mande SEMPRE timestamp UNIX (segundos ou milissegundos): funciona em QUALQUER versao. Data por extenso ('2026-07-01') so e aceita a partir da atualizacao de 26/07/2026; antes dela NAO da erro, devolve o relatorio INTEIRO ZERADO (vira 1970 por dentro). Se vier tudo zero e o funil tem cards, era isso — repita com timestamp."
       },
       {
         "name": "to",
         "type": "string",
         "location": "query",
         "required": false,
-        "description": "Fim do periodo (YYYY-MM-DD ou ISO 8601)"
+        "description": "Fim do periodo — mesma regra do 'from': timestamp UNIX e sempre seguro. A partir da atualizacao de 26/07/2026 aceita tambem data por extenso, e data SEM hora passa a cobrir o dia inteiro (ate 23:59:59)."
       },
       {
         "name": "user_ids",
@@ -4222,7 +4222,14 @@
         "type": "string",
         "location": "body",
         "required": false,
-        "description": "Instrucao IA para redigir o follow-up"
+        "description": "Instrucao IA para redigir o follow-up (LEGADO: vale como 1 etapa unica; so e usado quando follow_up_steps esta vazio)"
+      },
+      {
+        "name": "config.follow_up_steps",
+        "type": "array",
+        "location": "body",
+        "required": false,
+        "description": "Cadencia de follow-up: ate 3 etapas [{after_minutes, prompt}]. E ESTE o campo que a tela mostra em 'Instrucoes para a IA neste follow-up' e o que manda de verdade — tem precedencia sobre follow_up_time/follow_up_prompt. Cada after_minutes >= 5 (conta a partir da mensagem anterior) e a soma nao passa de 1440 min (24h). Ex.: [{\"after_minutes\":30,\"prompt\":\"Pergunte se ainda tem interesse\"}]. Aceita array ou string JSON."
       },
       {
         "name": "config.disabled_tools",
@@ -4440,7 +4447,14 @@
         "type": "string",
         "location": "body",
         "required": false,
-        "description": "Instrucao IA para redigir o follow-up"
+        "description": "Instrucao IA para redigir o follow-up (LEGADO: vale como 1 etapa unica; so e usado quando follow_up_steps esta vazio)"
+      },
+      {
+        "name": "config.follow_up_steps",
+        "type": "array",
+        "location": "body",
+        "required": false,
+        "description": "Cadencia de follow-up: ate 3 etapas [{after_minutes, prompt}]. E ESTE o campo que a tela mostra em 'Instrucoes para a IA neste follow-up' e o que manda de verdade — tem precedencia sobre follow_up_time/follow_up_prompt. Cada after_minutes >= 5 (conta a partir da mensagem anterior) e a soma nao passa de 1440 min (24h). Ex.: [{\"after_minutes\":30,\"prompt\":\"Pergunte se ainda tem interesse\"}]. Aceita array ou string JSON."
       },
       {
         "name": "config.disabled_tools",
@@ -22480,6 +22494,32 @@
     ],
     "related_tools": []
   },
+  {
+    "id": "lionchat_inboxes_waha_import_status",
+    "method": "GET",
+    "path": "/api/v1/accounts/{account_id}/inboxes/{inbox_id}/waha/import_status",
+    "title": "Andamento da Importacao de Historico (WhatsApp QR)",
+    "description": "[NOVO 2026-07-25] SO LEITURA: mostra em que pe esta a importacao de historico de uma caixa WhatsApp por QR (WAHA). Responde a pergunta 'a importacao parou?'. Campos: status ('idle' nunca rodou | 'importing' rodando | 'interrupted' caiu e VAI RETOMAR sozinha de onde parou | 'paused' pausada por alguem no painel de suporte, so volta no botao Retomar | 'cancelled' encerrada de vez | 'completed' concluida), started_at, completed_at, total_chats/processed_chats (conversas), total_messages/created_messages/skipped_messages (mensagens; skipped = ja existiam), contacts_created e error. ADMIN-ONLY, e so pra caixa WAHA (QR) — a caixa oficial (Cloud) usa lionchat_inboxes_whatsapp_history_status. Pausar, retomar e cancelar NAO existem no MCP: sao do painel de suporte.",
+    "category": "Caixas de Entrada",
+    "params": [
+      {
+        "name": "inbox_id",
+        "type": "integer",
+        "location": "path",
+        "required": true,
+        "description": "ID da caixa de entrada (WhatsApp por QR)"
+      }
+    ],
+    "returns": "situacao e progresso da importacao (status, contadores de conversas/mensagens/contatos, erro)",
+    "common_use_cases": [
+      "Cliente pergunta por que a importacao de historico parou ou sumiu",
+      "Acompanhar a migracao de um cliente novo (quantas conversas ja entraram)"
+    ],
+    "related_tools": [
+      "lionchat_inboxes_waha_status",
+      "lionchat_inboxes_whatsapp_history_status"
+    ]
+  },
   {
     "id": "lionchat_inboxes_failed_messages_summary",
     "method": "GET",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lionchat/mcp-server",
-  "version": "1.7.0",
+  "version": "1.8.1",
   "description": "MCP server for LionChat API — 547 tools + 10 resources + 9 prompts. Audit-log aware, completion API, progress notifications.",
   "type": "module",
   "main": "dist/index.js",