@lionchat/mcp-server 0.3.0 → 0.3.2

package/dist/docs/instructions.md

@@ -153,6 +153,12 @@ Quando precisar de detalhes profundos, leia um destes documents via `resources/r
 - `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
+- `lionchat://docs/conversation-flows` — Ciclo de vida de uma conversa (criação, auto-assignment, IA, resolução)
+- `lionchat://docs/kanban-deep-dive` — Estrutura completa do Kanban (Funnel/Stage/Item/pipeline)
+- `lionchat://docs/best-practices` — Como economizar tokens, evitar rate limit, ordem de operações
+- `lionchat://docs/troubleshooting` — Códigos HTTP, erros comuns, debugging
+- `lionchat://docs/flowbuilder-design-guide` — **OBRIGATÓRIO** antes de criar/editar fluxo: schema de nodes, handles expostos por tipo, layout/positioning, erros comuns, checklist
+- `lionchat://docs/flowbuilder-patterns` — 10 templates de fluxos prontos pra adaptar (saudação, captura, qualificação, CSAT, IA, etc)
 
 ## 9. Prompts pré-prontos (workflows automatizados)
 
@@ -162,6 +168,24 @@ O usuário pode invocar via slash command (`/nome_do_prompt`):
 - `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)
+- `inactive_contacts` — Contatos sem interação pra reativação
+- `team_load_balance` — Carga e distribuição da equipe
+- `quality_audit` — Auditoria de qualidade de conversas resolvidas
+- `whatsapp_template_usage` — Uso e performance de templates WhatsApp
+- `create_flow_brainstorm` — Banco de perguntas pra descobrir o que o cliente quer ANTES de criar um fluxo
+
+### Regras específicas para criação de FlowBuilder
+
+Quando o cliente pedir pra criar um fluxo:
+
+1. **Antes de gerar JSON**, avalie se você tem informação suficiente. Se faltar (canal, gatilho, conteúdo, ramificações), use o prompt `create_flow_brainstorm` como **guia de perguntas sugeridas** — escolha só as relevantes pro caso, não force checklist
+2. Fluxo simples (1-3 nodes, sem ramificação) → 2-3 perguntas bastam
+3. Fluxo complexo (5+ nodes, IA, API externa, várias ramificações) → vale aprofundar
+4. **SEMPRE consulte** `lionchat://docs/flowbuilder-design-guide` antes de chamar `flows_create` (schema, handles, layout)
+5. **SEMPRE verifique** se algum template em `lionchat://docs/flowbuilder-patterns` já resolve o caso — adaptar é mais seguro do que criar do zero
+6. **NUNCA crie** nodes sem `position: {x, y}` — eles ficam empilhados no canvas
+7. **NUNCA invente** `sourceHandle` — use só os listados no design guide por tipo de node (ex: condition usa `cond_0`/`cond_1`/`default`, não IDs livres)
+8. Antes de chamar `flows_create`, apresente um resumo em **linguagem natural** do que vai criar e confirme com o cliente
 
 ## 10. Idioma das respostas
 

package/dist/docs/prompts/create_flow_brainstorm.json

@@ -0,0 +1,9 @@
+{
+  "name": "create_flow_brainstorm",
+  "title": "Perguntas sugeridas para criar um FlowBuilder",
+  "description": "Banco de perguntas para descobrir o que o cliente quer ANTES de gerar o flow_data. Use APENAS as perguntas relevantes pro caso — nao force checklist. Fluxo simples (1-3 nodes) precisa de 2-3 perguntas no maximo; fluxo complexo (5+ nodes, ramificacoes, IA, API) vale aprofundar. Sempre consulte o resource lionchat://docs/flowbuilder-design-guide e lionchat://docs/flowbuilder-patterns antes de gerar o JSON.",
+  "arguments": [
+    { "name": "goal_hint", "description": "O que o cliente ja disse que quer (ex: 'fluxo de captura de lead')", "required": false }
+  ],
+  "template": "Cliente quer criar um fluxo no FlowBuilder do LionChat.\n\nObjetivo declarado: {{goal_hint|Nao informado}}\n\nINSTRUCAO: avalie o que o cliente JA disse e o que ainda falta saber. Pergunte SO o que falta. Nao force checklist. Em fluxo simples, 2-3 perguntas bastam. Em fluxo complexo, aprofunde.\n\nABAIXO esta o BANCO de perguntas sugeridas por categoria. ESCOLHA SO AS RELEVANTES.\n\n## Categoria A — Proposito e gatilho (quase sempre necessario)\n- Qual o objetivo do fluxo? (saudacao, qualificacao, captura, suporte, pos-venda, CSAT, agendamento, re-engajamento, outro)\n- Quando dispara? (mensagem recebida com palavra-chave, conversa criada, conversa resolvida, label aplicada, cron, webhook externo)\n- Se palavra-chave: quais palavras? Match exact ou contains?\n\n## Categoria B — Canal e escopo\n- Em qual canal vai rodar? (WAHA, WhatsApp Cloud, Webwidget, Telegram, Email, Twitter, Facebook, Instagram, Line, SMS, API, Voz, WhatsApp Business)\n- Em qual(is) inbox(es) especifica(s)? (peca o ID via inboxes_list se nao soube)\n- Tem filtro de quem entra? (so leads novos, so clientes existentes, so quem tem label X)\n\n## Categoria C — Conteudo da conversa\n- Vai mandar quais mensagens? Texto livre, templates WhatsApp aprovados, midia (imagem/audio/video), lista de botoes interativos?\n- Vai fazer perguntas pro cliente? Quantas? Quais?\n- Para cada pergunta: aceita qualquer resposta livre, opcoes fixas (ex: 1/2/3), ou regex (ex: CPF, email, telefone)?\n- Quanto tempo espera por cada resposta? (default sensato: 30-60 min)\n- O que mandar se nao responder no tempo? (mensagem de timeout, encerrar, escalar pra humano)\n\n## Categoria D — Captura, ramificacao e logica\n- Onde salva as respostas? Em variavel temporaria do flow, atributo da conversa, atributo do contato, custom_attributes\n- Tem ramificacao por condicao? Quais criterios? (ex: 'se valor > 1000 vai pra time premium')\n- Vai chamar API externa? (URL, metodo, headers, body, autenticacao)\n- Vai usar IA (Captain Assistant)? Em que momento? Pra que?\n  * generate = gerar resposta natural\n  * intent = classificar intencao da mensagem\n  * sentiment = analisar sentimento\n  * extract = extrair info estruturada (CPF, valor, etc)\n- Tem teste A/B? (randomizer)\n\n## Categoria E — Acoes finais\n- No fim do fluxo: criar card no Kanban? (em qual funil/etapa?) Atribuir agente/time? (ID) Adicionar/remover label? Mudar status/prioridade? Disparar webhook externo?\n- Tem criterio pra encerrar antes? (exit_conditions: ex: 'conversa marcada como resolvida' ou 'label X aplicada')\n\n## Antes de chamar flows_create\n1. Se faltou info CRITICA (ex: canal, gatilho, conteudo basico): pergunte agora\n2. Se a info que falta e mero detalhe: assuma defaults sensatos\n   - maxRetries: 3\n   - waitTime: 60min para resposta, 30min para timeouts\n   - sem ramificacao se cliente nao mencionou\n3. Apresente um RESUMO em linguagem natural do fluxo. Exemplo: 'Beleza, vou criar um fluxo assim: quando alguem mandar oi no WhatsApp, manda saudacao, pergunta se quer vendas/suporte, se vendas atribui ao time 1, se suporte ao time 2. Confirma?'\n4. Espere o cliente confirmar OU pedir ajustes\n5. So depois da confirmacao, chame flows_create\n6. ANTES de gerar o JSON: consulte lionchat://docs/flowbuilder-design-guide pra schema/handles/layout e lionchat://docs/flowbuilder-patterns pra ver se algum template ja resolve\n7. Apos gerar JSON, valide pelo checklist da secao 6 do design guide\n8. NUNCA crie node sem position. NUNCA invente sourceHandle.\n\nDEFAULTS SENSATOS quando cliente nao especificar:\n- channel_type: pergunte sempre, nao chute\n- inbox_ids: pergunte sempre\n- waitTime: 60 minutes\n- maxRetries: 3\n- waitUnit: minutes\n- saveTo: 'attribute' (conversa) na duvida\n- match_mode: 'contains' pra keywords"
+}

package/dist/docs/prompts/inactive_contacts.json

@@ -0,0 +1,23 @@
+{
+  "name": "inactive_contacts",
+  "title": "Contatos Inativos pra Reativação",
+  "description": "Identifica contatos sem interação há um tempo determinado, com sugestões de abordagem pra reativação.",
+  "arguments": [
+    {
+      "name": "days_inactive",
+      "description": "Dias sem interação (padrão: 30)",
+      "required": false
+    },
+    {
+      "name": "min_past_conversations",
+      "description": "Mínimo de conversas anteriores pra considerar (padrão: 1)",
+      "required": false
+    },
+    {
+      "name": "exclude_labels",
+      "description": "Labels pra excluir, separadas por vírgula (ex: 'spam,bot')",
+      "required": false
+    }
+  ],
+  "template": "Identifique contatos da conta que estão inativos há {{days_inactive|30}} dias ou mais.\n\nCritérios:\n- Tiveram pelo menos {{min_past_conversations|1}} conversa(s) anteriormente (mostra que já são leads ativos, não desconhecidos)\n- Última conversa marcada como `resolved` ou sem mensagens novas há {{days_inactive|30}}+ dias\n- Excluir contatos com labels: {{exclude_labels|none}}\n\nPra cada contato encontrado:\n1. Nome, telefone/email\n2. Última conversa (data, motivo do contato anterior se possível inferir)\n3. Canal favorito de contato (WhatsApp, Email, etc)\n4. Sugestão de abordagem personalizada:\n   - Se foi cliente: \"como pode ter ido com X que você comprou?\"\n   - Se foi lead frio: \"vimos seu interesse em Y, ainda faz sentido?\"\n   - Se foi pós-venda: \"vamos renovar?\" / \"feedback?\"\n\nApresentar no formato:\n- Resumo: X contatos identificados\n- Top 10 mais relevantes (priorizar valor histórico, segmento alto, label 'cliente')\n- Sugestão de mensagem template pra reativação em massa (se o usuário quiser, podemos criar campanha)"
+}

package/dist/docs/prompts/quality_audit.json

@@ -0,0 +1,28 @@
+{
+  "name": "quality_audit",
+  "title": "Auditoria de Qualidade do Atendimento",
+  "description": "Audita aleatoriamente conversas resolvidas pra checar qualidade: tempo de resposta, tom, resolução, follow-up.",
+  "arguments": [
+    {
+      "name": "period_days",
+      "description": "Quantos dias atrás analisar (padrão: 7)",
+      "required": false
+    },
+    {
+      "name": "sample_size",
+      "description": "Quantidade de conversas pra amostrar (padrão: 20)",
+      "required": false
+    },
+    {
+      "name": "agent_id",
+      "description": "Auditar agente específico (opcional)",
+      "required": false
+    },
+    {
+      "name": "inbox_id",
+      "description": "Auditar inbox específica (opcional)",
+      "required": false
+    }
+  ],
+  "template": "Faça uma auditoria de qualidade do atendimento nos últimos {{period_days|7}} dias.\n\nFiltros opcionais:\n- Agente: {{agent_id|todos}}\n- Inbox: {{inbox_id|todas}}\n\nAmostrar {{sample_size|20}} conversas RESOLVIDAS aleatoriamente desse período.\n\nPra cada conversa analisar:\n\n### Métricas Quantitativas\n- Tempo da primeira resposta (em minutos)\n- Tempo total de resolução\n- Número de mensagens trocadas\n- CSAT (se houver)\n- Foi reaberta depois? (indicador de problema mal resolvido)\n\n### Análise Qualitativa\n- Tom adequado? (formal/informal alinhado ao canal)\n- Cliente foi cumprimentado adequadamente?\n- Problema foi entendido na primeira interação?\n- Resposta foi clara e resolveu o problema?\n- Houve follow-up ou despedida adequada?\n- Erros gramaticais ou de português?\n\n### Red Flags a destacar\n- Tempo de primeira resposta > 30 min em horário comercial\n- Mais de 10 mensagens pra resolver questão simples\n- Resolução sem confirmação do cliente\n- Mensagens automáticas/copy-paste óbvios sem personalização\n- Tom inadequado (rude, robótico, condescendente)\n\n### Output\n\n## Sumário\n- Conversas auditadas: X\n- Qualidade Geral (1-10): Y\n- Tempo médio de primeira resposta\n- Taxa de reabertura\n\n## Top Problemas Encontrados\n(3-5 padrões recorrentes, com exemplos)\n\n## Top Boas Práticas Identificadas\n(2-3 exemplos pra replicar)\n\n## Recomendações\n- Treinamento focado em: ...\n- Templates de resposta padronizados pra: ...\n- Automações sugeridas: ...\n\nNão expor nomes de agentes em críticas públicas — apenas IDs em report interno."
+}

package/dist/docs/prompts/team_load_balance.json

@@ -0,0 +1,18 @@
+{
+  "name": "team_load_balance",
+  "title": "Carga e Balanceamento da Equipe",
+  "description": "Analisa distribuição de conversas entre agentes, identifica sobrecarregados e subutilizados.",
+  "arguments": [
+    {
+      "name": "period",
+      "description": "Período de análise: today, week, month (padrão: week)",
+      "required": false
+    },
+    {
+      "name": "team_id",
+      "description": "ID do time específico (opcional, se omitir analisa todos)",
+      "required": false
+    }
+  ],
+  "template": "Analise a carga de trabalho da equipe no período: {{period|week}}.\n\n{{team_id|Para todos os times.}}\nFiltrar por team_id={{team_id}} se especificado.\n\nDados a coletar pra cada agente:\n1. Conversas atribuídas (open + pending)\n2. Conversas resolvidas no período\n3. Tempo médio de primeira resposta\n4. Tempo médio de resolução\n5. % de conversas com CSAT (se houver)\n6. Status atual: online / offline / busy\n\nApresentar:\n\n## Visão Geral\n- Total de conversas ativas\n- Agentes online vs offline\n- Conversas sem atribuição (backlog)\n\n## Distribuição por Agente (tabela)\n| Agente | Ativas | Resolvidas | T. Resposta | T. Resolução | Status |\n\n## Identificar:\n- **Sobrecarregados**: > 1.5x média de conversas ativas → risco de queda na qualidade\n- **Subutilizados**: < 0.5x média → podem absorver mais\n- **Agentes offline com conversas pendentes**: redistribuir urgente\n- **Conversas órfãs**: sem assignee há > 1h → atribuir agora\n\n## Recomendações de ação\n- Lista de conversas pra reatribuir (com de → para)\n- Sugestão de revisão de assignment policy se houver desbalanceamento crônico\n- Conversas que talvez devam ser fechadas (sem resposta do cliente há > 7 dias)\n\nFinalizar perguntando se o usuário quer aplicar as redistribuições sugeridas."
+}

package/dist/docs/prompts/whatsapp_template_usage.json

@@ -0,0 +1,18 @@
+{
+  "name": "whatsapp_template_usage",
+  "title": "Uso e Performance de Templates WhatsApp",
+  "description": "Analisa quais templates WhatsApp estão sendo mais usados, eficácia, e templates aprovados mas sem uso.",
+  "arguments": [
+    {
+      "name": "inbox_id",
+      "description": "ID da inbox WhatsApp pra analisar (opcional, padrão: todas)",
+      "required": false
+    },
+    {
+      "name": "period_days",
+      "description": "Período em dias (padrão: 30)",
+      "required": false
+    }
+  ],
+  "template": "Analise o uso de templates WhatsApp Business nos últimos {{period_days|30}} dias.\n\nInbox: {{inbox_id|todas as inboxes WhatsApp Cloud}}\n\nDados a levantar:\n\n## 1. Inventário de Templates\n- Total de templates aprovados (status: APPROVED)\n- Pendentes de aprovação (PENDING)\n- Rejeitados (REJECTED) — listar motivos\n- Templates por categoria (UTILITY, MARKETING, AUTHENTICATION)\n- Templates por idioma\n\n## 2. Uso no Período\nPra cada template usado:\n- Nome do template\n- Quantas vezes foi enviado\n- Quantas conversas geraram resposta dentro de 24h\n- Taxa de resposta (% que responderam)\n- Taxa de conversão (se for marketing — virou venda/lead qualificado?)\n\n## 3. Templates Inativos\nListar templates aprovados HÁ MAIS DE 30 DIAS que NÃO foram usados no período.\n- Por quê? Esquecidos? Substituídos por novo?\n- Sugestão: arquivar / atualizar / promover uso\n\n## 4. Performance dos Top Templates\nTop 5 mais enviados — analisar:\n- Texto do template\n- Taxa de resposta\n- Tempo médio até resposta\n- Tem variáveis personalizadas? ({{nome}}, etc)\n- Categoria correta? (errar categoria = risco de banimento)\n\n## 5. Red Flags\n- Templates marketing sendo usados em janela 24h (deveriam ser utility)\n- Templates rejeitados não removidos\n- Templates aprovados há > 90 dias e nunca usados\n- Templates duplicados (mesma intenção, várias versões)\n\n## Recomendações\n- Templates a criar (gap identificado)\n- Templates a remover (desuso ou redundância)\n- Templates a otimizar (baixa conversão)\n- Sugestão de A/B test entre 2 versões de um mesmo template\n\nFinalizar com sugestão de criar nova campanha usando o template com melhor performance."
+}

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

@@ -0,0 +1,166 @@
+# Boas Práticas — Uso Eficiente do MCP
+
+Como usar o MCP do LionChat sem desperdiçar tokens, sem cair em rate limits, e com respostas precisas.
+
+## Princípio geral: liste resumido, leia detalhado quando precisar
+
+Errado: pegar TODAS conversas + TODAS mensagens de cada uma logo de cara.
+
+Certo:
+1. `conversations_list` com filtros e `page=1` (paginado) → vê IDs + última mensagem
+2. Identifica candidatas (5-10 conversas)
+3. `conversations_messages_list` SÓ para as relevantes
+
+Resultado: 10x menos tokens.
+
+## Use filtros sempre que possível
+
+A maioria dos endpoints aceita parâmetros pra filtrar antes de retornar:
+
+| Endpoint | Filtros úteis |
+|---|---|
+| `conversations_list` | `status` (open/resolved), `assignee_type`, `inbox_id`, `team_id`, `labels`, `q` (busca) |
+| `contacts_list` | `q` (nome/email/telefone), `include_contact_inboxes` |
+| `messages_search` | `q`, `conversation_id`, `before`, `after` |
+| `kanban_items_list` | `funnel_id`, `funnel_stage`, `assigned_agent_id` |
+| `reports_list_*` | `since`, `until`, `metric`, `type` |
+
+**Dica:** sempre filtre por período (`since`/`until`) em relatórios — sem isso pode trazer anos de histórico.
+
+## Paginação
+
+Endpoints listáveis paginam em geral 25 itens. Use `page` parameter:
+
+```
+page=1 → primeiros 25
+page=2 → próximos 25
+```
+
+Pra contar total, use `meta.total_count` (vem no response). Não tente "paginar até zerar" se já tem o total — pode ser milhões.
+
+## Cache local mental
+
+Quando ler dados que provavelmente não mudam na sessão:
+- Lista de inboxes
+- Lista de agentes
+- Lista de times
+- Custom attribute definitions
+- Funnels
+
+Faça UMA chamada e use a info por toda a conversa. NÃO refaça `agents_list` 10x.
+
+## Use endpoints específicos > endpoints genéricos
+
+Quando existir endpoint específico, prefira:
+
+| Errado | Certo |
+|---|---|
+| `reports_list` filtrando manualmente | `reports_list_2` (já é "conversations_metrics") |
+| `conversations_list` + filtro de unread no cliente | `conversations_list` com `assignee_type=me&status=open` |
+| `messages_list` percorrendo conversas | `conversations_messages_search` com `q=...` |
+
+## Economia em conversas com muitas mensagens
+
+Conversa com 200 mensagens? **Não baixe tudo**:
+
+1. `conversations_show` (1 chamada) → metadata + última mensagem
+2. Se precisa contexto: pegue só as últimas 20-30 mensagens com `before` ou `page`
+3. Pra análise completa, use `conversations_transcript` (formato condensado)
+
+## Operações em massa
+
+Pra atribuir labels, mover cards, etc em vários itens:
+- `kanban_bulk_bulk_actions` (cards Kanban)
+- `kanban_items_kanban_agents_create` em massa (passar array)
+- `automation_rules_*` (criar regras em vez de fazer manualmente)
+
+NÃO faça 50 PATCH requests individuais — bate rate limit.
+
+## Rate limiting
+
+LionChat tem rate limit por API token. Limites típicos:
+- ~500 req/min para read
+- ~100 req/min para write
+
+Se receber `429 Too Many Requests`:
+- Espere o `Retry-After` header
+- Reduza concorrência
+- Reavalie estratégia (provavelmente está fazendo loop ineficiente)
+
+## Quando NÃO usar IA pra escrever mensagens
+
+- Mensagens de cobrança / financeiras → use templates aprovados
+- Confirmação de venda → template + variáveis
+- Comunicação legal → revisão humana obrigatória
+
+IA é boa pra: triagem, classificação, resumo, sugestão de resposta, análise.
+
+## Variáveis de conta (account_variables)
+
+Pra dados que se repetem (slogans, endereços, horários):
+- `account_variables_create` UMA vez
+- Use em templates com `{{slogan}}`, `{{endereco}}`
+- Atualiza UMA vez, propaga pra todo lugar
+
+Nunca hard-code esses dados em respostas geradas.
+
+## Status codes a respeitar
+
+| Code | O que fazer |
+|---|---|
+| 200/201 | OK, processar resposta |
+| 204 | OK, sem corpo (típico de DELETE) |
+| 400 | Erro de input — leia mensagem e ajuste |
+| 401 | Token inválido/expirado — NÃO retry |
+| 403 | Sem permissão — não tente bypass |
+| 404 | Recurso não existe — talvez foi deletado |
+| 422 | Validação falhou — leia errors[] |
+| 429 | Rate limited — espere e retry |
+| 500/502/503 | Servidor — retry 1-2x com backoff |
+
+## Ordem de operações típicas
+
+### "Buscar todas conversas de um cliente específico"
+1. `contacts_search` com `q=email` → pega contact_id
+2. `contacts_show` com `include=conversations` OU
+3. Filter conversations: `conversations_list` com `q=email`
+
+### "Criar um card Kanban a partir de uma conversa"
+1. `funnels_list` → pegar funnel_id certo
+2. `kanban_items_create` com `funnel_id`, `funnel_stage` (geralmente primeira etapa), `conversation_display_id`
+3. Opcional: `item_details.value`, `assigned_agents`
+
+### "Resumir performance da equipe na semana"
+1. `agents_list` → IDs dos agentes
+2. `reports_list_*` (agent_overview) com `since=7d_ago`, `until=now`
+3. Sintetize: agente X com Y resoluções, tempo médio Z
+
+## Cuidados com tools de criação
+
+Endpoints `create_*` modificam dados reais. Antes de chamar:
+- Confirme com usuário (se inicialmente pediu "ver", não "fazer")
+- Verifique se o recurso já existe (evite duplicatas)
+- Use `dry_run` quando disponível
+
+## Erros comuns a evitar
+
+| Erro | Como evitar |
+|---|---|
+| Loop infinito de `page+1` | Sempre cheque `meta.total_count` e pare |
+| Re-listar inboxes 20x | Cache mental |
+| Mandar `conversations_messages_create` sem `message_type` | Sempre setar `incoming`/`outgoing` |
+| Listar TODAS contas de um agente direto | Use filter `q=nome` primeiro |
+| Esquecer de filtrar por `account_id` | Multi-tenant — sempre escopar |
+
+## Quando agir vs quando perguntar
+
+Aja sem perguntar:
+- Listagem, filtro, busca, leitura
+- Sumarização, classificação
+- Sugestão de próximos passos
+
+Pergunte primeiro:
+- Criar / atualizar / deletar dados
+- Enviar mensagem pra cliente
+- Mudar status de várias conversas em massa
+- Alterar configuração de conta/inbox

package/dist/docs/resources/conversation-flows.md

@@ -0,0 +1,208 @@
+# Fluxos de Conversação
+
+Como conversas atravessam o LionChat: criação, auto-assignment, IA, automações, resolução. Use quando precisar entender ou diagnosticar comportamento de conversações.
+
+## Ciclo de vida de uma conversa
+
+```
+                          [Cliente envia 1ª msg]
+                                  │
+                                  ▼
+                    ┌──────────────────────────┐
+                    │ ContactInbox criado/      │
+                    │  encontrado por source_id │
+                    └─────────┬────────────────┘
+                              ▼
+                    ┌──────────────────────────┐
+                    │  Conversation.create     │
+                    │  status: 0 (open)        │
+                    └─────────┬────────────────┘
+                              ▼
+                  ┌───────────────────────────┐
+                  │ Greeting (se ativo)       │ → Message outgoing
+                  └─────────┬─────────────────┘
+                            ▼
+                  ┌───────────────────────────┐
+                  │ AutomationRule:            │
+                  │ "conversation_created"     │
+                  └─────────┬─────────────────┘
+                            ▼
+                  ┌───────────────────────────┐
+                  │ Auto-assignment:           │
+                  │ - team OU agent           │
+                  │ - via policy ou simples   │
+                  └─────────┬─────────────────┘
+                            ▼
+                  ┌───────────────────────────┐
+                  │ Captain (IA) Agent:        │
+                  │ se atribuído              │
+                  │ → debounce → LLM response │
+                  └─────────┬─────────────────┘
+                            ▼
+                  ┌───────────────────────────┐
+                  │ Conversa ativa             │
+                  │ (status: open)            │
+                  └─────────┬─────────────────┘
+                            ▼
+              [Agente humano ou IA atende ↔ cliente]
+                            │
+                    ┌───────┴────────┐
+                    ▼                ▼
+            [resolvida]      [adiada]
+            status: 1        status: 3
+                    │                │
+                    │                └──→ desnooze automático
+                    ▼
+              ┌───────────────────────────┐
+              │ Pós-resolução:             │
+              │ - Captain memory + FAQ    │
+              │ - Reporting events        │
+              │ - Automation rules        │
+              │ - CSAT survey send        │
+              └────────────────────────────┘
+```
+
+## Etapas detalhadas
+
+### 1. Criação da conversa
+
+Mensagem chega via webhook do canal (WAHA, WhatsApp Cloud, Email, etc) → `Webhook::IncomingMessageJob` ou similar → `IncomingMessageService` → cria/encontra `Contact`, `ContactInbox`, `Conversation`, `Message`.
+
+**Pontos importantes:**
+- `Conversation` sempre criada com `status = 0` (open)
+- `inbox_id` setado direto
+- `assignee_id` começa `null` (pendente atribuição)
+- `captain_assistant_id` começa `null` (a menos que automação atribua)
+
+### 2. Greeting (mensagem de boas-vindas)
+
+Se `inbox.greeting_enabled = true`:
+- Após criar a conversa, envia `inbox.greeting_message`
+- Vira `Message` outgoing automática
+- NÃO substitui resposta humana — só inicia a conversa
+
+### 3. AutomationRule: "conversation_created"
+
+Cada inbox/conta pode ter regras com `event_name: 'conversation_created'`. Elas rodam **antes** do auto-assignment.
+
+Ações comuns:
+- Atribuir agente/time específico
+- Adicionar labels
+- Marcar prioridade
+- Atribuir Captain Assistant (`captain_assistant_id`)
+
+Avaliação:
+- Condições combinadas com AND
+- Operadores: `equal_to`, `contains`, `includes`, `is_present`
+- Pode usar `inbox`, `content`, `country_code`, `email`, custom_attributes
+
+### 4. Auto-assignment
+
+Roda após automation rules. Lógica simplificada:
+
+```
+SE inbox.enable_auto_assignment_v2:
+  SE inbox.assignment_policy associada:
+    → Política decide (round-robin, balanced, etc)
+  SENAO:
+    → assignee_id fica null (manual)
+```
+
+V2 (Assignment Policy) é o motor moderno. V1 (campo `auto_assignment` simples) é legado.
+
+### 5. Captain (IA Agente)
+
+Se `captain_assistant_id` foi setado (manual ou via automação):
+- Mensagem incoming dispara `Captain::ResponseBuilderJob`
+- Job tem **debounce** (~10s) — agrupa mensagens em rajada
+- Chama LLM com prompt do assistant + histórico
+- LLM pode invocar tools (FAQ, update_contact, create_booking, etc)
+- Resposta vira `Message` outgoing com `sender_type: Captain::Assistant`
+
+**Quando IA é desativada manualmente:**
+- Agente clica em "Desativar AI" → `captain_assistant_id` vira null
+- `custom_attributes.captain_manually_disabled = true`
+- IA não responde mais nessa conversa (mesmo se nova msg)
+
+### 6. Estado "pending" (status 2)
+
+Conversa em "pending" significa "aguardando algo":
+- Cliente respondeu mas agente ainda não viu
+- OU agente respondeu e tá aguardando cliente
+- Geralmente movida automaticamente por automação ("se 24h sem resposta → pending")
+
+### 7. Resolução (status 1)
+
+Agente clica em "Resolver":
+- `status` → 1 (resolved)
+- `resolved_at` setado
+- Dispara `conversation_resolved` event
+- Listeners agem:
+  - `CaptainListener`: gera memory + FAQ se IA atendeu
+  - `HookListener`: dispara webhooks
+  - `AutomationRuleListener`: regras de `conversation_resolved`
+  - `ReportingEventListener`: salva métricas
+  - `CsatSurveyJob` (se config ativa): envia pesquisa CSAT
+
+### 8. Snoozed (status 3)
+
+Adia conversa:
+- `status` → 3 (snoozed)
+- `snoozed_until` setado (datetime futuro)
+- Job periódico `ReopenSnoozedConversationsJob` roda e reabre quando passa do `snoozed_until`
+
+### 9. Reopen
+
+Conversa resolvida que recebe nova mensagem do cliente:
+- Comportamento depende de config `inbox.lock_to_single_conversation`
+- Default: cria NOVA conversa (mantém histórico)
+- Se locked: reabre a mesma conversa (`status` volta a 0)
+
+## Estado relacional
+
+```
+Conversation
+  ├─ messages: array em ordem cronológica
+  ├─ contact: quem é o cliente
+  ├─ inbox: canal de origem
+  ├─ assignee: agente humano atual (null OK)
+  ├─ team: time atribuído (null OK)
+  ├─ captain_assistant: IA atribuída (null OK)
+  ├─ kanban_item: card vinculado (null OK)
+  └─ labels: tags aplicadas
+```
+
+## Como diagnosticar problemas
+
+### "Conversa não atribuiu ninguém"
+
+1. `inbox.enable_auto_assignment_v2` está true?
+2. `inbox.assignment_policy` está setado?
+3. Tem `InboxMember` ativos pra essa inbox?
+4. Tem `automation_rule` que poderia ter atribuído antes?
+
+### "IA não respondeu"
+
+1. `conversation.captain_assistant_id` está setado?
+2. Account tem OpenAI hook configurado?
+3. Captain feature ativa na conta? (`feature_captain_integration`)
+4. Custom attr `captain_manually_disabled = true`?
+5. Sidekiq job `Captain::ResponseBuilderJob` rodou? Tem erro no log?
+
+### "Conversa marcada como pending sem motivo"
+
+1. Tem automation rule com `event_name: conversation_updated` ou similar?
+2. Tem SLA policy ativando state change?
+3. Veio de external API call?
+
+## Eventos importantes (pra automation)
+
+| Evento | Quando dispara |
+|---|---|
+| `conversation_created` | Nova conversa |
+| `conversation_opened` | Status volta pra open (reabertura) |
+| `conversation_resolved` | Agente resolve |
+| `conversation_pending` | Status muda pra pending |
+| `conversation_updated` | Qualquer update |
+| `message_created` | Nova mensagem (incoming ou outgoing) |
+| `first_reply_created` | Primeira resposta humana |