@lionchat/mcp-server 1.27.0 → 1.28.0

package/dist/docs/instructions.md

@@ -396,6 +396,26 @@ trava a criação.
 
 **NUNCA sobrescreva por inferência dados já preenchidos.** Em especial, **NUNCA sobrescreva telefone ou e-mail existente de um contato** — se já há valor preenchido, pergunte antes de alterar.
 
+**O cliente mudou de número? NÃO é `lionchat_contacts_update`.** Trocar `phone_number` por lá muda o
+que aparece na tela e **não redireciona as mensagens**: o endereço de entrega vem do crachá de cada
+caixa e de um cache por contato, não da ficha. Medido em 01/10/2026 — depois de editar só a ficha, todas
+as conversas seguiam enviando para o número ANTIGO nos dois canais de WhatsApp, sem erro nenhum.
+
+| Situação | Tool |
+|---|---|
+| A pessoa **mudou de número** | `lionchat_contacts_change_phone` |
+| **Corrigir erro de digitação** no cadastro de quem nunca conversou | `lionchat_contacts_update` |
+
+`lionchat_contacts_change_phone` mantém a mesma conversa, acerta o endereço nas duas caixas de WhatsApp,
+escreve uma pílula registrando a mudança e limpa a marca "não tem WhatsApp" do número antigo. Recusa
+quando o número é o mesmo, é inválido, o contato é um **grupo**, ou o número já pertence a outra ficha
+(devolve 409 dizendo de quem é).
+
+**Quando o número já é de outra ficha:** o parâmetro `merge_with` junta as duas e troca numa operação
+só — mas **apaga** a outra ficha e **não tem como desfazer**. Antes de usar, chame
+`lionchat_contact_merge_preview`, **mostre ao usuário o que será descartado e espere a confirmação
+dele**. Nunca use `merge_with` por conta própria.
+
 ## 8. Índice de roteamento (intenção → tool certa)
 
 Antes de escolher a ferramenta, cheque se a intenção bate com a coluna da direita. Erros comuns aqui levam a ações de escrita disfaradas de leitura.

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

@@ -463,6 +463,22 @@ Meta só aceita isso num **dataset vinculado à WABA**, nunca no pixel do site (
   `lionchat:caixa_sem_token`, `lionchat:dataset_id_invalido`, `lionchat:desligado_pelo_cliente`,
   `lionchat:nome_sem_equivalente_whatsapp`; da Meta: `"<subcode>: <mensagem>"` (ex.: 2804087 = clique
   do anúncio inválido/expirado).
+- **Caixa QR Code (WhatsApp não oficial) atribui campanha pelo MESMO caminho que a oficial** (desde
+  01/10/2026). A identidade do negócio é a **Página do Facebook que rodou o anúncio** no lugar da
+  conta do WhatsApp Business (que caixa de QR Code não tem), e o evento vai para o pixel que a conta
+  já usa. Vale a régua normal: `degraded=true` + `fallback_reason` + `action_source`.
+  `action_source: business_messaging` = saiu como anúncio de WhatsApp; `website` = saiu como site.
+  **É um evento só** — quando a Meta recusa o de mensagem, ele é reenviado como site
+  automaticamente, e o motivo fica em `fallback_reason`.
+  **Motivo mais comum nessa caixa:** `"2804065: ..."` — a Página do anúncio não está vinculada ao
+  conjunto de dados. O cliente resolve sozinho no Gerenciador de Eventos da Meta (abrir o conjunto de
+  dados > Configurações > Dados vinculados > conectar a Página). Cabe **uma** Página por conjunto de
+  dados. Outros: `"2804072: ..."` (clique e Página de anúncios diferentes) e `"2804087: ..."` (clique
+  inválido ou expirado).
+  **NÃO existe mais** `qr_page_attribution` na resposta, nem os motivos `dataset_indisponivel`,
+  `sem_pagina_do_anuncio`, `pagina_sem_conexao` e `dataset_e_o_proprio_pixel`: o desenho de 30/09 que
+  criava um conjunto de dados próprio para a Página foi removido em 01/10 (exigia a permissão
+  `page_events`, que o aplicativo só tem em acesso padrão, e entregou zero em produção).
 - Recusa ao vincular (422 com `subcode`, ex.: 2804116 / "whatsapp_business_manage_events"): a chave da
   caixa não tem a permissão — reconectar a caixa pelo Cadastro Incorporado da Meta; nunca pedir o token
   do pixel para isso. Um 401/403 da caixa NUNCA desliga o pixel da conta (site, formulário e agenda
@@ -559,6 +575,13 @@ com uma única agenda liberada ela assume essa; com duas ou mais, recusa nomeand
 restringir quais agendas a IA oferece, continua valendo `captain_assistants_update` com
 `config.booking_event_type_ids`.
 
+**1-A. Quem limita a busca de horário é o DONO, não a IA (01/10/2026).** A janela de busca sai do
+`max_advance_days` do tipo de agendamento; sem limite configurado, vale o teto de 30 dias. A IA não
+consegue mais encurtar essa busca: ela varre dia a dia até achar vaga ou bater no limite. Consequência
+para quem configura pelo conector: se a IA está dizendo que "não há horário", o número a conferir é o
+`max_advance_days` do tipo (`lionchat_booking_event_types_update`), não o comportamento da IA. Agenda com
+vaga só daqui a 20 dias e janela configurada em 7 nunca oferece nada.
+
 **2. A IA entrega o link do Meet sozinha.** O link do Google Meet não existe no instante em que o
 agendamento é criado (nasce depois da ida ao Google), e antes a IA prometia o link e nunca voltava.
 Agora o sistema arma uma volta de ~25s; sem link ainda, ele remarca sozinho (+40s) sem gastar turno

package/dist/docs/resources/glossary.md

@@ -514,6 +514,14 @@ cards daquele funil).
 - **Plano B** (`fallback_reason` no `meta_capi_events`): o evento de anúncio saiu como SITE. O motivo
   fica gravado (`lionchat:*` nosso ou `"<subcode>: <mensagem>"` da Meta); na tela é o selo âmbar
   "site (plano B)" e o filtro "Só plano B" (`degraded=true` na API).
+- **Atribuição de campanha em caixa QR Code** (desde 2026-10-01): caixa de QR Code não tem conta do
+  WhatsApp Business, então a identidade do negócio no evento é a **Página do Facebook que rodou o
+  anúncio** (`page_id` no `user_data`), e o destino é o pixel que a conta já usa. Daí em diante vale
+  a régua normal: `action_source` diz se saiu como `business_messaging` ou `website`, e
+  `fallback_reason` diz por que degradou. **Um evento por conversão** — nunca dois.
+  Para a campanha contar, o cliente precisa ter vinculado a Página ao conjunto de dados no
+  Gerenciador de Eventos da Meta; sem isso a recusa é `2804065` e o evento sai como site.
+  O campo `qr_page_attribution`, que existiu entre 30/09 e 01/10/2026, **não existe mais**.
 
 ## Idiomas da plataforma (2026-06)
 

package/dist/docs/resources/troubleshooting.md

@@ -617,6 +617,42 @@ 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/`.
 
+## Conector REMOTO parou de funcionar e só volta reconectando na mão — CORRIGIDO na v1.27.0
+
+Vale SÓ para o conector remoto (`mcp.lionchat.com.br`). O conector local (npm, stdio) nunca teve isso.
+
+Sintoma, como o cliente relata: *"o MCP caiu"*, *"deu Server not initialized"*, *"parou de responder e
+só voltou quando eu desconectei e conectei o conector de novo"*. Todas as chamadas falham, não só
+algumas, e **não volta sozinho** — nem esperando, nem fechando e abrindo o chat. O que resolve é ir em
+Conectores e reconectar.
+
+Causa (até a v1.26.1): o servidor guardava cada conexão **na memória**. Quando o pod reiniciava (deploy,
+troca de nó, queda de máquina), a memória ia embora e o pedido seguinte do cliente recebia
+`400 Server not initialized`. O programa do cliente trata só 401/403/405 e **desiste em definitivo** com
+qualquer outro código — ele nunca descarta o número de sessão por conta própria. Daí o "só volta
+reconectando": reconectar é o único jeito de ele pedir um número novo.
+Caso real (01/10/2026): um cliente levou **28 recusas em 2 minutos** e ficou sem o MCP até alguém
+reconectar; ninguém foi avisado de nada.
+
+Correção (v1.27.0, 01/10/2026): o servidor não guarda mais sessão — cada pedido se resolve sozinho com
+as credenciais que já vêm nele. O número de sessão antigo passa a ser ignorado em vez de recusado, e o
+reinício do pod fica invisível para quem está usando.
+
+O que NÃO mudou, para quem perguntar:
+- A conta em que a IA age continua a mesma (a escolha do `lionchat_switch_account` é guardada e lida em
+  todo pedido novo). **Mudou um detalhe:** a conta escolhida agora vale para TODAS as janelas daquela
+  pessoa. Antes, cada janela tinha a sua — mas só até a próxima reconexão, que acontece sozinha a cada
+  poucos minutos, e então herdava a da outra. Era imprevisível, não isolamento.
+- O catálogo do ChatGPT (modo enxuto, 35 ferramentas na vitrine + o balcão que alcança as 935) é idêntico.
+- O `ping` de 30 s contra o corte do Cloudflare continua ativo (seção acima).
+
+Interruptor: `MCP_STATELESS` (`off` volta ao modo antigo, com sessão). Nasce ligado.
+Detalhe e medições: `docs/plans/mcp-sessao-sobrevive-reinicio/design.md` no repo `lionchat-mcp-remote`.
+
+**Se o sintoma voltar na v1.27.0 ou depois, NÃO é esta causa** — era por construção, e há rede de teste
+cobrindo. Procurar outra: token expirado (401), conector apontando para endereço errado, ou o canal de
+avisos sendo cortado (seção acima).
+
 ## "O grupo não recebeu o resumo diário" (Avisos de relatório) — 27/08
 
 Diagnóstico em 2 passos: `lionchat_report_alerts_list` (colunas `last_delivery_status`/`last_error`

package/endpoints.json

@@ -290,7 +290,7 @@
   "method": "PATCH",
   "path": "/api/v1/accounts/{account_id}/contacts/{id}",
   "title": "Atualizar Contato",
-  "description": "Atualiza um contato. Aceita name, email, phone_number, identifier, custom_attributes, additional_attributes, blocked, avatar/avatar_url. NUNCA sobrescreva phone_number/email ja preenchido sem confirmacao. TELEFONE UNICO POR CONTA (trava no banco desde 01/09/2026): trocar phone_number para um numero que ja e de outro contato da conta = 422 'phone_number has already been taken'. EMPRESA (2026-09-25): aceita company_id (ver param); o contato devolve company_id. Cargo da pessoa = additional_attributes.job_title.",
+  "description": "Atualiza um contato. Aceita name, email, phone_number, identifier, custom_attributes, additional_attributes, blocked, avatar/avatar_url. NUNCA sobrescreva phone_number/email ja preenchido sem confirmacao. ATENCAO — TROCAR DE NUMERO NAO E AQUI: mudar `phone_number` por esta rota muda o que aparece na tela mas NAO redireciona as mensagens, porque o endereco de entrega vem do cracha de cada caixa e de um cache por contato. Medido em 01/10: depois de editar so a ficha, todas as conversas seguiam enviando pro numero ANTIGO nos dois canais de WhatsApp, sem erro nenhum. Para trocar de numero de verdade use lionchat_contacts_change_phone. Esta rota serve para CORRIGIR o cadastro (erro de digitacao em contato que nunca conversou).",
   "category": "Contatos",
   "params": [
    {
@@ -319,7 +319,7 @@
     "type": "string",
     "location": "body",
     "required": false,
-    "description": "Telefone"
+    "description": "Telefone. So para CORRIGIR o cadastro — nao redireciona o envio. Troca de numero de verdade: lionchat_contacts_change_phone"
    },
    {
     "name": "identifier",
@@ -371,6 +371,7 @@
    "Atualização em massa via automação"
   ],
   "related_tools": [
+   "lionchat_contacts_change_phone",
    "lionchat_contacts_update_1"
   ]
  },
@@ -29885,6 +29886,102 @@
    "lionchat_contacts_show"
   ]
  },
+ {
+  "id": "lionchat_contacts_change_phone",
+  "method": "POST",
+  "path": "/api/v1/accounts/{account_id}/contacts/{id}/change_phone",
+  "title": "Trocar o Telefone do Contato (mantendo a conversa)",
+  "description": "Troca o telefone de um contato MANTENDO a mesma conversa no painel. Use SEMPRE esta rota quando a pessoa mudou de numero — nunca lionchat_contacts_update, que muda a ficha e NAO redireciona as mensagens (o endereco de entrega vem do cracha de cada caixa e de um cache por contato, nao da ficha). Esta rota mexe nas quatro pecas: telefone da ficha, cracha de cada caixa de WhatsApp (QR Code e oficial), crachas extras (saem de circulacao, com as conversas reapontadas) e o cache de LID. Escreve uma pilula de atividade nas conversas do contato dizendo de qual numero para qual, e limpa a marca \"nao tem WhatsApp\" do numero antigo (que tirava a pessoa de toda campanha). No QR Code, a forma canonica do numero e perguntada ao WhatsApp antes de gravar — isso resolve sozinho o caso do nono digito. RECUSA (nao troca) quando: o numero e o mesmo, e invalido, o contato e um GRUPO, ou o numero ja pertence a outra ficha (409 com quem e o dono). OPCIONAL merge_with: junta as fichas E troca numa so operacao, com ESTA ficha sobrevivendo e a outra sendo APAGADA — so aceita a ficha dona do numero, exige permissao de excluir contato, e NAO tem como desfazer. Antes de usar merge_with, consulte lionchat_contact_merge_preview para saber o que sera descartado e CONFIRME com a pessoa.",
+  "category": "Contatos",
+  "params": [
+   {
+    "name": "account_id",
+    "type": "integer",
+    "location": "path",
+    "required": true,
+    "description": "ID da conta"
+   },
+   {
+    "name": "id",
+    "type": "integer",
+    "location": "path",
+    "required": true,
+    "description": "ID do contato que vai trocar de numero"
+   },
+   {
+    "name": "phone_number",
+    "type": "string",
+    "location": "body",
+    "required": true,
+    "description": "Numero novo. Aceita com ou sem \"+\" (e normalizado para E.164)"
+   },
+   {
+    "name": "merge_with",
+    "type": "integer",
+    "location": "body",
+    "required": false,
+    "description": "ID da ficha a ser ABSORVIDA (e APAGADA) quando o numero novo ja pertence a ela. So aceita a ficha dona do numero. Exige permissao de excluir contato. Irreversivel — confirme antes"
+   }
+  ],
+  "returns": "200 { trocou, antigo, novo, crachas_atualizados, crachas_arquivados, conversas_reapontadas, conversas_avisadas }; 409 { error: \"telefone_de_outro_contato\", conflito: { id, name, phone_number } } quando o numero ja e de outra ficha; 422 { error } para telefone_igual, telefone_invalido, contato_de_grupo ou merge_with_nao_e_dono_do_numero",
+  "common_use_cases": [
+   "O cliente avisou que mudou de numero e quer continuar o atendimento na mesma conversa",
+   "A clinica ou integracao informou um telefone novo para o mesmo paciente",
+   "Juntar a ficha duplicada que ja usa o numero novo e passar a usar esse numero (merge_with)"
+  ],
+  "related_tools": [
+   "lionchat_contact_merge_preview",
+   "lionchat_contacts_show",
+   "lionchat_contacts_update"
+  ]
+ },
+ {
+  "id": "lionchat_contact_merge_preview",
+  "method": "GET",
+  "path": "/api/v1/accounts/{account_id}/actions/contact_merge/preview",
+  "title": "Previa da Mesclagem de Contatos",
+  "description": "Diz o que a mesclagem VAI fazer, sem executar nada. Use SEMPRE antes de mesclar ou de usar merge_with, e mostre o resultado para a pessoa confirmar: mesclar APAGA uma ficha e NAO tem como desfazer. Devolve quem fica, quem deixa de existir, os campos que entram nos vazios do sobrevivente, os que serao DESCARTADOS (quando os dois tem valor diferente), quantas conversas vem, quantas vao aparecer encerradas, as etiquetas que somam e se a ficha vai ficar bloqueada. Regra de quem vence, campo a campo: o sobrevivente ganha onde ELE tem valor; onde esta vazio, recebe o do outro. Leitura pura; exige a mesma permissao de mesclar (excluir contato).",
+  "category": "Contatos",
+  "params": [
+   {
+    "name": "account_id",
+    "type": "integer",
+    "location": "path",
+    "required": true,
+    "description": "ID da conta"
+   },
+   {
+    "name": "base_contact_id",
+    "type": "integer",
+    "location": "query",
+    "required": true,
+    "description": "ID do contato que SOBREVIVE"
+   },
+   {
+    "name": "mergee_contact_id",
+    "type": "integer",
+    "location": "query",
+    "required": true,
+    "description": "ID do contato que sera APAGADO"
+   },
+   {
+    "name": "phone_number",
+    "type": "string",
+    "location": "query",
+    "required": false,
+    "description": "Numero que a ficha vai adotar depois da juncao. Sem ele, a previa anuncia o telefone do absorvido como \"descartado\" — o que seria mentira no caminho da troca de telefone"
+   }
+  ],
+  "returns": "200 { fica: {id,name}, sai: {id,name}, entra: [{key,label,value}], descartado: [{key,label,atual,descartado}], telefone_novo, conversas, conversas_que_serao_fechadas, etiquetas_novas, vai_ficar_bloqueado }",
+  "common_use_cases": [
+   "Mostrar ao usuario o que se perde antes de confirmar a mesclagem de duas fichas",
+   "Conferir, antes de usar merge_with na troca de telefone, o que sera descartado"
+  ],
+  "related_tools": [
+   "lionchat_contacts_change_phone",
+   "lionchat_contacts_show"
+  ]
+ },
  {
   "id": "lionchat_contacts_active",
   "method": "GET",
@@ -32148,7 +32245,7 @@
   "method": "POST",
   "path": "/api/v1/accounts/{account_id}/funnels/{funnel_id}/meta_capi_events/{id}/retry",
   "title": "Reenviar Evento Meta CAPI falhado",
-  "description": "AÇÃO DE ESCRITA. Reenfileira UM evento Meta CAPI com status 'failed' (volta pra pending e o job envia de novo). Só failed: qualquer outro status responde 422 {error:'not failed'}. 404 se não for deste funil.",
+  "description": "ACAO DE ESCRITA. Reenfileira UM evento Meta CAPI que esta retentavel: status 'failed' OU 'pending' ABANDONADO (parado ha mais de 15 min). Volta pra pending e o job envia de novo, limpando o motivo da falha e o do plano B. Qualquer outro status responde 422 {error:'not retryable'}. 404 se o evento nao for deste funil.",
   "category": "Integracoes",
   "params": [
    {
@@ -32166,7 +32263,7 @@
     "description": "ID do evento falhado"
    }
   ],
-  "returns": "200 {ok: true} | 422 {error:'not failed'} | 404 {error:'not found'}",
+  "returns": "200 {ok: true} | 422 {error:'not retryable'} | 404 {error:'not found'}",
   "common_use_cases": [
    "Reenviar a conversão depois de corrigir o token/pixel"
   ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lionchat/mcp-server",
-  "version": "1.27.0",
+  "version": "1.28.0",
   "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",