@lionchat/mcp-server 0.2.1 → 0.3.0

package/dist/docs/instructions.md

@@ -0,0 +1,184 @@
+# LionChat — Instruções para a IA conectada
+
+Você está conectado ao LionChat, uma plataforma brasileira de atendimento multi-canal (multi-channel customer support) com CRM, IA Agente, automações, agenda e relatórios. Este documento explica como pensar nos dados, interpretar respostas e escolher as ferramentas certas.
+
+**Idioma de saída:** sempre português brasileiro (PT-BR). Termos técnicos da API podem permanecer em inglês quando padronizados (status, payload, endpoint).
+
+## 1. Modelo de dados central
+
+```
+Account (conta/empresa)
+ ├─ User (agente humano)
+ ├─ Inbox (canal: WhatsApp, Email, Instagram, Widget, etc)
+ │   └─ Channel-specific config (Channel::Waha, Channel::Whatsapp, etc)
+ ├─ Contact (cliente final)
+ │   └─ ContactInbox (vínculo Contact ↔ Inbox)
+ ├─ Conversation (thread de atendimento)
+ │   ├─ Message (mensagem individual)
+ │   │   └─ Attachment (arquivo: imagem, audio, video, pdf)
+ │   └─ ConversationParticipants (agentes/times atribuídos)
+ ├─ KanbanItem (card do CRM, vinculado a Conversation opcional)
+ │   ├─ KanbanChecklist (lista de tarefas dentro do card)
+ │   └─ KanbanNote (notas privadas no card)
+ ├─ Funnel (funil Kanban) → FunnelStage (etapas)
+ ├─ AutomationRule (regras de automação)
+ ├─ Captain::Assistant (AI Agente / IA de atendimento)
+ ├─ AccountTask (agenda/tarefas)
+ └─ Booking (agendamento de demonstração/reunião)
+```
+
+**Multi-tenancy:** tudo é escopado por `account_id`. Uma conta NUNCA enxerga dados de outra. O `account_id` vem do contexto da sessão MCP — você NÃO precisa passar manualmente nas chamadas.
+
+## 2. Status codes e enums (glossário rápido)
+
+### Conversation.status (inteiro)
+- `0` = `open` (aberta — em atendimento)
+- `1` = `resolved` (resolvida — fechada como sucesso)
+- `2` = `pending` (pendente — aguardando alguém)
+- `3` = `snoozed` (adiada — voltará a aparecer em data futura)
+
+### Message.message_type (inteiro)
+- `0` = `incoming` (cliente → empresa)
+- `1` = `outgoing` (empresa → cliente)
+- `2` = `activity` (evento do sistema, ex: "Elvis atribuiu a conversa")
+- `3` = `template` (template aprovado WhatsApp Cloud API)
+
+### Attachment.file_type (string ou inteiro)
+- `image` — fotos/imagens
+- `audio` — áudios (geralmente vêm com `transcribed_text`)
+- `video`
+- `file` — PDF, DOCX, qualquer outro (pode ter `extracted_text`)
+- `location`, `contact` — tipos especiais
+
+### KanbanItem.item_details.priority (string)
+- `urgent`, `high`, `medium`, `low`, `none`
+
+### AccountUser.role (string)
+- `agent` (atendente comum)
+- `administrator` (admin/dono)
+
+## 3. Convenções da API
+
+### Datas
+- **Formato:** ISO 8601 com timezone, ex: `"2026-05-18T14:32:00-03:00"`
+- **Timezone padrão:** `America/Sao_Paulo` (BRT, UTC-3)
+- **Timestamps Unix** aparecem em alguns campos (ex: `last_activity_at`) — sempre em segundos, não milissegundos
+
+### Paginação
+- Query param `page` (1-indexado)
+- `per_page` padrão 25, máximo 100 (clamp server-side)
+- Resposta inclui `meta` com contadores globais
+
+### Autenticação
+- Header `api_access_token` (NUNCA na URL)
+- Para você (IA via MCP), isso é resolvido automaticamente
+
+### Identificação de recursos
+- IDs internos: número inteiro (`id: 123`)
+- `display_id`: número visível na UI da conversa (use este pra falar com humanos)
+- `source_id`: ID externo da plataforma origem (ex: `wamid.xxx` do WhatsApp)
+
+## 4. Workflows típicos
+
+### Listar conversas abertas
+```
+lionchat_conversations_list (status: 'open', assignee_type: 'all')
+```
+
+### Ver mensagens de uma conversa
+```
+lionchat_conversations_messages_list (conversation_id: 123)
+```
+
+### Criar contato + conversa
+```
+1. lionchat_contacts_search (verificar se já existe pelo telefone/email)
+2. Se não existe: lionchat_contacts_create
+3. lionchat_inboxes_public_conversations_create (vincula contato à inbox)
+```
+
+### Criar card Kanban a partir de uma conversa
+```
+1. lionchat_kanban_v2_create (account_id, funnel_id, contact_id, conversation_id, stage)
+```
+
+### Relatório de produtividade
+```
+1. lionchat_reports_summary (visão geral)
+2. lionchat_reports_list (por agente — passa since/until ISO 8601)
+3. Comparar avg_first_response_time entre agentes
+```
+
+### Mudar conta ativa (somente Conector OAuth)
+```
+1. lionchat_list_my_accounts (ver todas)
+2. lionchat_switch_account (id: X)
+```
+
+## 5. Boas práticas para economizar tokens e tempo
+
+### ✅ Faça
+- **Filtre antes de listar:** sempre que possível use `status`, `since`, `inbox_id`
+- **Use endpoints de resumo:** `lionchat_reports_summary`, `lionchat_conversations_meta` quando o usuário pediu apenas números
+- **Pense em paginação:** se há 5000 conversas, NÃO liste tudo — pegue meta primeiro
+- **Reuse contexto:** se acabou de listar conversas, não chame de novo pra "verificar"
+
+### ❌ Evite
+- Chamar 50 endpoints sequencialmente sem estratégia
+- Listar conteúdo completo quando o usuário pediu só contagem
+- Ignorar filtros e baixar dataset inteiro
+- Chamar a mesma ferramenta repetidamente em loop (rate limit detecta isso)
+
+## 6. Limites da plataforma (do lado do servidor)
+
+| Limite | Valor |
+|---|---|
+| `per_page` max | 100 |
+| Bulk actions (IDs) max | 100 por chamada |
+| Rate limit leitura | 1200/min por token |
+| Rate limit escrita | 600/min por token |
+| Loop detection | bloqueia chamada idêntica >10x em 10s |
+
+## 7. Quando NÃO chamar nenhuma ferramenta
+
+- Conversa social: "oi", "bom dia", "obrigado" → responda direto, não invoque tools
+- Pergunta conceitual: "o que é Kanban?" → explique do seu conhecimento, não chame nenhum endpoint
+- O usuário já tem a info na tela e está pedindo interpretação → use o que ele já mostrou
+
+## 8. Resources disponíveis (leia sob demanda)
+
+Quando precisar de detalhes profundos, leia um destes documents via `resources/read`:
+
+- `lionchat://docs/glossary` — Glossário completo de termos, status, enums
+- `lionchat://docs/data-model` — Modelo de dados detalhado, FKs, índices
+- `lionchat://docs/reports-guide` — Como interpretar cada um dos 19 endpoints de relatório
+- `lionchat://docs/api-conventions` — Auth, paginação, filtros, errors, rate limits
+
+## 9. Prompts pré-prontos (workflows automatizados)
+
+O usuário pode invocar via slash command (`/nome_do_prompt`):
+
+- `productivity_report` — Relatório de produtividade da equipe
+- `stuck_leads` — Leads parados há N dias no Kanban
+- `weekly_recap` — Resumo da semana
+- `customer_health` — Saúde completa de 1 cliente (conversas + Kanban + CSAT)
+
+## 10. Idioma das respostas
+
+Sempre responda em **PT-BR**. Quando mencionar termos técnicos padronizados da API, mantenha em inglês entre parênteses na primeira ocorrência:
+- "conversa aberta (open)"
+- "ID de exibição (display_id)"
+- "carga útil (payload)"
+
+Isso ajuda o usuário a casar o que você diz com a API/documentação.
+
+## 11. Quando errar uma chamada
+
+Se uma ferramenta retornar erro:
+- `HTTP 401/403`: você ou o usuário perdeu permissão → reporte claramente, não retente
+- `HTTP 404`: o recurso não existe → confirme o ID antes de tentar de novo
+- `HTTP 422`: parâmetro inválido → leia a mensagem, corrija
+- `HTTP 429`: rate limit → espere 1 minuto antes de retentar
+- `HTTP 5xx`: erro do servidor → retente 1 vez com backoff; se falhar de novo, reporte
+
+NUNCA entre em loop de retry. Se errou 2 vezes, pare e reporte.

package/dist/docs/prompts/customer_health.json

@@ -0,0 +1,13 @@
+{
+  "name": "customer_health",
+  "title": "Saúde do Cliente (visão 360°)",
+  "description": "Visão completa de um cliente específico: todas conversas, cards Kanban, CSAT histórico, engajamento, sinais de churn. Use pra preparar reuniões, antes de ligar pro cliente, ou pra entender por que ele tá quieto.",
+  "arguments": [
+    {
+      "name": "contact_identifier",
+      "description": "Nome, email, telefone OU ID do contato",
+      "required": true
+    }
+  ],
+  "template": "Gere visão **360° do cliente** identificado por: **{{contact_identifier}}**\n\n## Passos\n\n1. **Localize o contato** (use `lionchat_contacts_search` com `q={{contact_identifier}}`):\n   - Se múltiplos resultados, mostre os top 3 e peça confirmação\n   - Se nenhum, reporte e pare\n\n2. **Detalhes do contato** (use `lionchat_contacts_show`):\n   - Nome, email, telefone, identifier\n   - custom_attributes (importante! pode ter dados de negócio)\n   - Empresa vinculada (se houver)\n   - Data de criação no LionChat\n\n3. **Histórico de conversas** (use `lionchat_contacts_list` com filtro contact_id):\n   - Total de conversas com esse cliente\n   - Status atual: quantas abertas, resolvidas, pendentes\n   - Últimas 5 conversas (com data e display_id)\n\n4. **Conversa mais recente** (use `lionchat_conversations_messages_list` da última conversa):\n   - Pegue as últimas 10 mensagens pra contexto\n   - Identifique tom (cordial, irritado, satisfeito)\n   - Status atual e último agente atribuído\n\n5. **Cards Kanban vinculados** (use `lionchat_kanban_items_filter` por conversation_display_ids):\n   - Em quais funis está\n   - Etapas atuais\n   - Valor total no pipeline\n\n6. **CSAT histórico** (use `lionchat_csat_list` filtrando por contact_id se possível, senão por conversas dele):\n   - Notas recebidas, feedbacks\n   - Tendência (melhorando/piorando)\n\n7. **Engajamento** (calcule a partir dos dados):\n   - Frequência de interação (conversas/mês)\n   - Tempo desde última conversa (sinal de churn?)\n   - Taxa de resposta dele (incoming vs outgoing)\n\n## Apresentação\n\n```markdown\n# 👤 Cliente: [Nome] — Visão 360°\n\n## 📇 Identificação\n- **Email:** ...\n- **Telefone:** ...\n- **Empresa:** ...\n- **Cadastrado em:** DD/MM/YYYY (X meses atrás)\n- **Custom:** [campos relevantes do custom_attributes]\n\n## 📊 Status\n- **Health Score:** 🟢 Saudável / 🟡 Atenção / 🔴 Risco\n- **Última interação:** DD/MM/YYYY (X dias atrás)\n- **Conversas totais:** N | Abertas: M | Resolvidas: K\n- **CSAT médio:** X⭐ (baseado em N respostas)\n\n## 💰 Pipeline (Kanban)\n- **Funil [X]:** Etapa Y — R$ Z (parado há W dias)\n- **Funil [X2]:** Etapa Y2 — R$ Z2\n\n## 💬 Última Conversa (#display_id)\n- **Data:** DD/MM HH:MM\n- **Status:** Aberta/Resolvida\n- **Agente:** Nome\n- **Resumo (2-3 linhas):** O que aconteceu na última interação\n- **Tom percebido:** Cordial / Frustrado / Satisfeito\n\n## ⚠️ Sinais de Alerta\n[Lista sinais detectados:]\n- Sem interação há >30 dias\n- Última CSAT foi 2⭐\n- Card parado em \"Negociação\" há 21 dias\n- Cliente comentou \"vou avaliar concorrentes\"\n\n## 💡 Próximos Passos Sugeridos\n[2-3 ações concretas:]\n1. Ligar pra entender por que parou de responder\n2. Mover card pra etapa \"Em risco\"\n3. Enviar pesquisa de feedback\n```\n\n## Health Score (como calcular)\n\n- 🟢 **Saudável:** última interação <30d + CSAT ≥4 + sem sinais negativos\n- 🟡 **Atenção:** última interação 30-90d OU CSAT 3-3.9 OU card parado >14d\n- 🔴 **Risco:** última interação >90d OU CSAT <3 OU múltiplos cards parados OU mensagens frustradas recentes\n\n## Importante\n\n- Seja honesto no Health Score. Não infle: 🟢 só se realmente saudável.\n- **Não invente sinais.** Só liste o que viu nos dados.\n- Se cliente é novo (<30 dias), avise: \"Pouco histórico, score preliminar\".\n- Se múltiplos contatos com o mesmo nome, peça pra desambiguar antes de continuar.\n- Datas em PT-BR (DD/MM/YYYY)."
+}

package/dist/docs/prompts/productivity_report.json

@@ -0,0 +1,13 @@
+{
+  "name": "productivity_report",
+  "title": "Relatório de Produtividade da Equipe",
+  "description": "Compila relatório completo de produtividade da equipe por período. Inclui métricas por agente (tempo médio de primeira resposta, resolução, conversas atendidas, CSAT), comparativo entre agentes, destaque de top performers e gargalos.",
+  "arguments": [
+    {
+      "name": "period_days",
+      "description": "Quantos dias atrás analisar (default: 7)",
+      "required": false
+    }
+  ],
+  "template": "Gere um **Relatório de Produtividade da Equipe** dos últimos {{period_days|7}} dias.\n\n## Passos a executar\n\n1. **Calcule o período:** since = {{period_days|7}} dias atrás (Unix timestamp em segundos), until = agora\n\n2. **Resumo geral da conta** (use `lionchat_reports_summary` com type='account', business_hours=true):\n   - Total de conversas, taxa de resolução, tempo médio de primeira resposta e resolução\n   - Compare com período anterior (campo `previous` da resposta)\n\n3. **Performance por agente** (use `lionchat_reports_list` com type='agent', mesmo since/until):\n   - Liste cada agente com: conversas atendidas, avg_first_response_time, avg_resolution_time, CSAT médio\n   - Identifique TOP 3 (por volume + qualidade combinados)\n   - Identifique 3 com maior tempo de resposta (potenciais gargalos)\n\n4. **CSAT** (use `lionchat_csat_metrics` com mesmo período):\n   - Média geral, distribuição (5⭐, 4⭐, ...)\n   - Taxa de resposta CSAT\n\n5. **SLA** (use `lionchat_sla_metrics` se disponível):\n   - Hit rate, breach count\n\n## Como apresentar\n\nFormate em **markdown** com:\n\n```markdown\n# 📊 Relatório de Produtividade — Últimos {{period_days|7}} dias\n\n## Visão Geral\n| Métrica | Esta semana | Semana anterior | Variação |\n|---|---|---|---|\n| Conversas | X | Y | +/-Z% |\n| Tempo médio 1ª resposta | X min | Y min | +/-Z% |\n| Tempo médio resolução | X h | Y h | +/-Z% |\n| Taxa de resolução | X% | Y% | +/-Z% |\n\n## Top 3 Agentes\n1. **Nome** — X conversas, Y min 1ª resposta, CSAT Z⭐\n2. ...\n3. ...\n\n## Pontos de Atenção\n- Agente XYZ com tempo de resposta 3x acima da média\n- Inbox WhatsApp com volume crescendo\n\n## CSAT\n- Média: X⭐ (anterior: Y⭐)\n- Taxa de resposta: Z%\n\n## SLA\n- Hits: X% (meta 95%)\n- Breaches: Y conversas\n```\n\n## Conversões importantes\n\n- TODOS os tempos retornados estão em **segundos**. Converta:\n  - < 60s → mostre em segundos\n  - 60-3600s → mostre em minutos (`X min`)\n  - 3600-86400s → mostre em horas (`X h Y min`)\n  - \\> 86400s → mostre em dias\n- Datas: use formato brasileiro (DD/MM ou DD/MM HH:MM)\n- Taxas (CSAT, SLA hit rate): mostre como %\n\n## Importante\n\n- Se não tiver dados suficientes (período sem atividade), diga claramente em vez de inventar números\n- Se algum agente tem 0 conversas, OMITA da listagem em vez de mostrar zerado (não inflar lista)\n- Use emojis com moderação (📊 ⭐ 🚨) — máximo 1 por seção"
+}

package/dist/docs/prompts/stuck_leads.json

@@ -0,0 +1,18 @@
+{
+  "name": "stuck_leads",
+  "title": "Leads Parados no Kanban",
+  "description": "Identifica leads (cards Kanban) parados há mais de N dias na mesma etapa. Lista priorizando por valor e tempo parado. Sugere ações para destravar.",
+  "arguments": [
+    {
+      "name": "days_stuck",
+      "description": "Mínimo de dias parado pra considerar (default: 7)",
+      "required": false
+    },
+    {
+      "name": "funnel_id",
+      "description": "ID do funil específico (default: todos)",
+      "required": false
+    }
+  ],
+  "template": "Encontre **leads parados no Kanban há mais de {{days_stuck|7}} dias** e gere um plano de ação.\n\n## Passos\n\n1. **Lista funis ativos** (use `lionchat_funnels_list`):\n   - Se {{funnel_id}} foi passado, filtra só ele\n   - Senão, lista todos não-arquivados\n\n2. **Para cada funil, lista cards** (use `lionchat_kanban_items_list` ou `lionchat_kanban_items_filter`):\n   - Filtre por `stage_entered_at` < {{days_stuck|7}} dias atrás\n   - Ordene por `item_details.value` desc (maiores valores primeiro)\n   - Pegue top 20 (não inunde o usuário)\n\n3. **Para cada card relevante, busque contexto** (se houver `conversation_display_id`):\n   - Use `lionchat_conversations_show` pra pegar última atividade\n   - Verifique se conversa ainda está ativa\n\n4. **Categorize por gravidade**:\n   - 🔴 CRÍTICO: parado >14 dias E valor > R$ 5.000\n   - 🟡 ATENÇÃO: parado >7 dias E valor > R$ 1.000\n   - 🟢 MONITORAR: parado >7 dias E valor < R$ 1.000\n\n## Apresentação\n\n```markdown\n# 🚨 Leads Parados — Kanban\n\n**Critério:** parados há mais de {{days_stuck|7}} dias.\n**Encontrados:** N cards.\n\n## 🔴 Críticos (urgente)\n\n### Lead: [Nome do contato] — R$ X.XXX\n- **Funil:** Nome do funil\n- **Etapa:** Nome da etapa (parado há X dias)\n- **Última conversa:** Y dias atrás\n- **Ação sugerida:** Reabrir conversa / Ligar / Mover pra Perdido\n\n## 🟡 Atenção\n...\n\n## 🟢 Monitorar\n...\n\n## Resumo\n- Total parado: N cards (R$ X em valor combinado)\n- Tempo médio parado: Y dias\n- Etapa com mais parados: [nome]\n```\n\n## Ações sugeridas (escolha com base no contexto)\n\n- **Última conversa <7 dias:** Reabra a conversa e dê follow-up\n- **Última conversa 7-30 dias:** Envie mensagem de reengajamento\n- **Última conversa >30 dias:** Considere mover pra etapa \"Perdido\" (não vale manter no funil)\n- **Sem conversa nenhuma:** Crie conversa de outreach\n- **Valor alto + parado >14 dias:** Sinalize pra você (o usuário) ligar pessoalmente\n\n## Importante\n\n- Não execute ações automaticamente — apenas SUGIRA. O usuário decide.\n- Se a quantidade for grande (>50 cards), peça permissão antes de listar todos.\n- Use valores reais (não invente). Se um card não tem `value`, mostre \"sem valor\".\n- Datas em formato brasileiro (DD/MM/YYYY)."
+}

package/dist/docs/prompts/weekly_recap.json

@@ -0,0 +1,7 @@
+{
+  "name": "weekly_recap",
+  "title": "Resumo Semanal Executivo",
+  "description": "Resumo executivo de tudo que aconteceu na semana: atendimento, vendas (Kanban), IA, gargalos. Pensado pra quem precisa de visão rápida pra decidir.",
+  "arguments": [],
+  "template": "Gere um **Resumo Executivo da Semana** — visão rápida pra tomar decisões.\n\n## Passos\n\n1. **Calcule período:** since = 7 dias atrás, until = agora\n\n2. **Atendimento** (use `lionchat_reports_summary`, business_hours=true):\n   - Total de conversas, resolvidas, abertas, pendentes\n   - Comparativo com semana anterior\n   - Tempo médio de resposta e resolução\n\n3. **Pipeline Kanban** (use `lionchat_funnels_list` + `lionchat_kanban_items_counts` por funil):\n   - Para cada funil: total de cards, valor total no funil, cards entrados na semana, cards movidos pra \"Fechado\"\n   - Calcular taxa de conversão (fechados / total entrados)\n\n4. **IA** (use `lionchat_captain_assistants_list`):\n   - Quantos assistentes ativos\n   - Conversas atendidas pela IA (campo `active_conversations_count`)\n\n5. **CSAT** (use `lionchat_csat_metrics`):\n   - Média da semana, comparativo com anterior\n\n6. **SLA** (use `lionchat_sla_metrics`):\n   - Hits e breaches\n\n7. **Top 3 Inboxes** (use `lionchat_reports_list_2`):\n   - Quais canais mais movimentaram\n\n## Apresentação\n\n```markdown\n# 📅 Resumo da Semana — DD/MM a DD/MM\n\n## 🎯 Destaque da Semana\n[Uma frase com o ponto mais importante: \"Crescemos 20% em conversas mas CSAT caiu 0.3⭐\" ou \"Funil Vendas com R$ 50K parados na etapa Proposta\"]\n\n## 📞 Atendimento\n- **N conversas** (vs N anterior, +/- X%)\n- **N resolvidas** (taxa: X%)\n- **Tempo médio 1ª resposta:** X min\n- **CSAT:** X⭐ (anterior: Y⭐)\n\n## 💰 Vendas (Pipeline)\n- **Funil [Nome]:** N cards (R$ XK total)\n  - Entraram: N | Fechados: M | Conversão: Z%\n  - Em risco (parados >7d): K cards\n\n## 🤖 IA\n- **N agentes ativos**\n- **N conversas atendidas** pela IA esta semana\n- Conversas resolvidas pela IA sem handoff: M (estimativa)\n\n## ⚠️ Pontos de Atenção\n- [3 alertas concretos, ex:]\n  - SLA: X conversas estouraram\n  - Funil Y com gargalo na etapa Z\n  - Agente W com tempo médio 2x acima da equipe\n\n## 💡 Recomendações\n[2-3 ações concretas pra próxima semana]\n```\n\n## Importante\n\n- **Seja conciso.** Resumo executivo = 1 página, não 5. Cortar > inflar.\n- **Compare sempre com semana anterior** (campo `previous` dos endpoints).\n- **Destaque tendências, não números crus.** \"Crescemos 20%\" > \"De 100 pra 120\".\n- **3 atenções, 3 recomendações.** Se quiser mais, peça permissão.\n- Use emojis (📅 📞 💰 🤖 ⚠️ 💡) — 1 por seção pra escaneabilidade rápida.\n- Datas em PT-BR (DD/MM/YYYY).\n- Valores em R$ (formato brasileiro: R$ 1.234,56)."
+}

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

@@ -0,0 +1,257 @@
+# Convenções da API LionChat
+
+Padrões de autenticação, paginação, filtros, formatos e tratamento de erros. Use sempre que precisar entender COMO chamar a API ou interpretar respostas genéricas.
+
+## Autenticação
+
+### Tipos de auth
+
+| Tipo | Header / Param | Quando usar |
+|---|---|---|
+| `api_access_token` | Header `api_access_token: <token>` | API principal (você usa isto via MCP) |
+| Devise Token Auth | `access-token` + `client` + `uid` | Dashboard web/mobile (não você) |
+| HMAC | `X-Webhook-Signature` | Webhooks de entrada |
+| OAuth Bearer | `Authorization: Bearer <token>` | MCP Remote (você usa isto) |
+
+Pra você via MCP: tudo já tá resolvido. O servidor MCP injeta o token correto em cada chamada.
+
+### Token escopos
+
+Tokens são **por usuário**, não por conta. O mesmo token funciona em qualquer conta que o usuário tem acesso. O scoping por conta acontece via `account_id` no path.
+
+## Paginação
+
+### Query params padrão
+
+- `page` (int, 1-indexado, default 1)
+- `per_page` (int, default varia por endpoint, máximo 100 clamp server-side)
+
+### Resposta típica
+
+```json
+{
+  "data": [ ... ],
+  "meta": {
+    "current_page": 1,
+    "total_pages": 5,
+    "total_count": 142,
+    "has_more": true
+  }
+}
+```
+
+Ou para listas grandes (cursors):
+
+```json
+{
+  "data": [ ... ],
+  "meta": {
+    "before": "...",
+    "after": "...",
+    "has_more": true
+  }
+}
+```
+
+### Estratégia recomendada
+
+- Para listar tudo: **NÃO** itere infinitamente. Sempre limite (`per_page=100` + 1 página é geralmente suficiente).
+- Para "quantos X tem": prefira endpoints `meta` ou `count`.
+- Para encontrar X específico: prefira `search` ou `filter` (server-side).
+
+## Filtros
+
+### Por query string (simples)
+
+```
+?status=open&priority=high&assignee_type=me
+```
+
+### Por POST body (complexo, multiplos campos)
+
+`POST /api/v1/accounts/X/conversations/filter`
+```json
+{
+  "payload": [
+    { "attribute_key": "status", "filter_operator": "equal_to", "values": ["open"] },
+    { "attribute_key": "labels", "filter_operator": "includes", "values": ["urgente"] }
+  ]
+}
+```
+
+### Operadores aceitos
+
+- `equal_to` / `not_equal_to`
+- `contains` / `does_not_contain`
+- `is_present` / `is_not_present`
+- `is_greater_than` / `is_less_than`
+- `is_in` / `is_not_in` (arrays)
+- `includes` / `excludes` (relacionamentos)
+- `before` / `after` (datas)
+
+## Formatos de Data
+
+### Quando enviar (input)
+
+- **Preferir ISO 8601 com timezone:** `"2026-05-18T14:32:00-03:00"`
+- **Unix timestamp em segundos** funciona em endpoints de reports
+- Datas sem timezone → assumido `America/Sao_Paulo`
+
+### Quando receber (output)
+
+- Campos `*_at` (created_at, updated_at): ISO 8601 com timezone
+- Campos `last_activity_at`, `waiting_since`: **Unix timestamp em SEGUNDOS** (não milissegundos)
+- Sempre confira: se número, é Unix; se string, é ISO
+
+### Timezone
+
+- Default: `America/Sao_Paulo` (UTC-3, sem DST atualmente)
+- Conta pode ter `locale` próprio mas timezone segue config do servidor
+- Pra evitar bugs, sempre passe timezone explícito
+
+## Códigos HTTP
+
+### Sucesso
+
+| Código | Significado |
+|---|---|
+| `200` OK | Sucesso, body com dados |
+| `201` Created | Recurso criado, body com o novo recurso |
+| `202` Accepted | Aceito pra processamento async (Sidekiq) |
+| `204` No Content | Sucesso sem body (ex: DELETE) |
+
+### Erros do cliente
+
+| Código | Significado | O que fazer |
+|---|---|---|
+| `400` Bad Request | Parâmetros mal formados | Confira sintaxe |
+| `401` Unauthorized | Token inválido ou expirado | Reporte ao usuário (não retente) |
+| `403` Forbidden | Sem permissão (papel insuficiente) | Reporte (não retente) |
+| `404` Not Found | Recurso não existe (ou de outra conta) | Confira ID |
+| `422` Unprocessable Entity | Validação falhou | Leia mensagem, corrija |
+| `429` Too Many Requests | Rate limit | Espere 60s antes de retentar |
+
+### Erros do servidor
+
+| Código | Significado | O que fazer |
+|---|---|---|
+| `500` Internal Server Error | Erro inesperado | Retente 1x com backoff |
+| `502/503/504` | Servidor indisponível | Retente com backoff exponencial |
+
+## Tratamento de erros padrão
+
+Body de erro típico:
+
+```json
+{
+  "error": "Validation failed",
+  "errors": {
+    "name": ["can't be blank"]
+  }
+}
+```
+
+Ou simples:
+
+```json
+{
+  "error": "Conversation not found"
+}
+```
+
+Ou com código:
+
+```json
+{
+  "error_code": "LIONLAB_PLAN_INSUFFICIENT",
+  "message": "Plan upgrade required"
+}
+```
+
+## Idempotência
+
+| Método | Idempotente? | Significado |
+|---|---|---|
+| `GET` | ✅ Sim | Pode retentar livremente |
+| `HEAD` | ✅ Sim | Idem |
+| `PUT`, `PATCH` | ✅ Sim | Atualizar 2x dá mesmo resultado |
+| `DELETE` | ✅ Sim | Apagar 2x → primeiro OK, segundo 404 (ainda idempotente em efeito final) |
+| `POST` | ❌ Geralmente NÃO | Criar 2x cria 2 registros |
+
+**Estratégia:** GET pode retentar. POST que falha → confirmar via GET se foi criado antes de retentar.
+
+## Rate Limiting
+
+| Limite | Padrão | Janela |
+|---|---|---|
+| Por IP global | 3000 reqs | 1 min |
+| Por token API (writes) | 600 reqs | 1 min |
+| Por token API (reads) | 1200 reqs | 1 min |
+| Loop detection | 10 reqs idênticas | 10 seg |
+
+Quando rate-limited:
+- Status `429 Too Many Requests`
+- Header `Retry-After` indica em quantos segundos voltar
+
+**NÃO entre em loop de retry.** Espere o tempo, retente 1x. Se falhar de novo, reporte.
+
+## Endpoints especiais
+
+### Bulk actions
+
+`POST /bulk_actions` aceita arrays de IDs. **Máximo 100 IDs por chamada**.
+
+```json
+{
+  "type": "Conversation",
+  "ids": [1, 2, 3, ...],   // max 100
+  "action_name": "assign_agent",
+  "action_attributes": { "assignee_id": 6 }
+}
+```
+
+### Search
+
+`GET /search?q=texto` — busca cross-entidade (conversations, contacts, messages)
+
+`GET /search/contacts?q=texto` — só contatos
+
+`GET /search/conversations?q=texto` — só conversas
+
+## Headers úteis pra mandar
+
+- `Accept: application/json` (sempre)
+- `Content-Type: application/json` (ao mandar body)
+- `User-Agent: nome-da-IA` (ajuda no debug do nosso lado)
+
+## Headers úteis pra ler na resposta
+
+- `X-Total-Count`: total de itens (em listagens)
+- `Link`: paginação cursors (RFC 5988)
+- `X-RateLimit-Remaining`: quantas chamadas restam no minuto
+- `X-RateLimit-Reset`: timestamp Unix de reset
+
+## Endpoints públicos vs autenticados
+
+### Públicos (sem token)
+- `/api/v1/widget/*` — widget de chat ao vivo (auth via `website_token` query)
+- `/api/v1/inboxes/:inbox_identifier/contacts/*` — API pública pra criar contatos (Client API)
+- `/api/v1/booking/:public_id` — agendamentos públicos
+
+### Privados (token obrigatório)
+- Todo o resto em `/api/v1/accounts/:account_id/*`
+
+Pra você via MCP: você sempre tem token. Os endpoints públicos raramente são úteis no seu fluxo.
+
+## Versionamento
+
+- `/api/v1/*` — estável, breaking changes em V2 hipotético
+- `/api/v2/*` — funcionalidades novas / breaking changes (poucas hoje: reports principalmente)
+
+## Lições importantes
+
+1. **Sempre escopa por account_id** — esse é o filtro mais importante. Não pule.
+2. **Use endpoints específicos sobre genéricos** — `lionchat_conversations_search` é melhor que listar tudo e filtrar.
+3. **Trate erros gracefully** — não retente 401/403/422 (são erros permanentes). Retente só 5xx e 429 com backoff.
+4. **Cache não existe na API** — toda chamada hit no banco. Se chamar 100x a mesma coisa, pesa.
+5. **`per_page` MAX é 100** — independente do que você pedir. Server-side clamp.