@lionchat/mcp-server 1.10.1 → 1.10.3

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
@@ -283,6 +338,42 @@ Cancelar vale pra TODOS os grupos (inclusive `permanent`, `window_expired`, `cam
 que nunca seriam reenviados) — é assim que se limpa o painel. Ações irreversíveis: confirme com o
 usuário e mostre as contagens do summary antes.
 
+### "Erro 131026 / Message undeliverable" — NUNCA chute a causa (30/07)
+A Meta devolve o MESMO código 131026 pra duas coisas diferentes: **o número não tem WhatsApp** e **a
+pessoa não está recebendo** (bloqueou, aparelho fora, não aceita mensagem de empresa). A Meta não diz
+qual das duas — então a plataforma carimba um fato NOSSO em
+`content_attributes.undeliverable_history`:
+
+| Carimbo | O que significa | O que dizer ao cliente |
+|---|---|---|
+| `never_delivered` | nunca entregamos nada pra esse contato | provavelmente o número não tem WhatsApp — vale conferir o número |
+| `delivered_before` | já entregamos antes, hoje não entrega | o número existe; a pessoa é que não está recebendo agora |
+| ausente (mensagem antiga) | sem histórico carimbado | enuncie as DUAS possibilidades, sem escolher |
+
+**Nunca afirme "esse número não tem WhatsApp" sem o carimbo `never_delivered`.** Foi exatamente esse
+palpite que fez atendente encerrar conversa de paciente que existia (conta 56, conv 3629).
+
+### "Mídia recusada pela Meta (131053) e a faixa vermelha sumiu sozinha" (30/07)
+Comportamento novo, não é bug. O 131053 é um balde: uma das variantes (a que menciona `weblink`) é
+TRANSITÓRIA — o buscador da Meta falhou ao baixar o arquivo pela URL. Nesse caso a plataforma reenvia
+sozinha, agora por upload direto, e a mensagem fica verde sem precisar de F5. As demais variantes do
+131053 (formato/tamanho recusado) NÃO são resgatadas — regra fail-closed de propósito, pra não ficar
+reenviando eternamente algo que a Meta nunca vai aceitar.
+
+### "A mensagem falhou dizendo 'Template not found or invalid template name'" (30/07)
+Se a caixa é **WhatsApp oficial** e faz mais de 24h que o cliente não fala, a causa quase sempre é a
+**janela de 24h fechada** — não um template faltando. Até 30/07 o erro gravado era esse texto
+enganoso; hoje a mensagem diz que a janela fechou, e o classificador põe a falha no grupo
+`window_expired` (fora do reenvio em lote — reenviar não adiantaria).
+
+Regras de produto pra explicar ao cliente:
+- **Mandar template NÃO abre a janela.** Só a mensagem do CLIENTE abre.
+- Fora da janela, só template aprovado sai. Texto livre é recusado pela Meta.
+- O follow-up automático da IA passou a entender isso: fora das 24h ele escolhe um modelo aprovado em
+  vez de escrever texto livre e tomar recusa (ver `lionchat://docs/best-practices`).
+- Erro sem tradução deixou de existir: todo `external_error` agora vira texto em português na bolha e
+  no painel de falhas. Se aparecer erro em inglês cru pro usuário, isso é reportável.
+
 ### "O Messenger parou de enviar / 'Invalid parameter'" (24/07)
 Causa raiz do apagão de 22 a 24/07: a Meta **aposentou a message tag** que o sistema mandava em todo
 envio de Messenger. Corrigido em 24/07. Agora o Messenger respeita a **janela de 24h** de verdade: