@lionchat/mcp-server 0.4.5 → 0.4.7

package/dist/docs/instructions.md

@@ -68,6 +68,10 @@ Account (conta/empresa)
 - Query param `page` (1-indexado)
 - `per_page` padrão 25, máximo 100 (clamp server-side)
 - Resposta inclui `meta` com contadores globais
+- **Atenção:** o tamanho da página é por-endpoint e às vezes **FIXO**, ignorando `per_page`:
+  - **Conversas** = 25 fixo (`app/finders/conversation_finder.rb:250`)
+  - **Contatos** = 15 fixo (`contacts_controller.rb:12`)
+  - Nesses casos, para pegar mais resultados pagine por `page` — aumentar `per_page` não tem efeito.
 
 ### Autenticação
 - Header `api_access_token` (NUNCA na URL)
@@ -121,10 +125,28 @@ Mais em `lionchat://docs/glossary` → "Quando usar campo nativo vs custom_attri
 
 ## 4. Workflows típicos
 
-### Listar conversas abertas
-```
-lionchat_conversations_list (status: 'open', assignee_type: 'all')
-```
+### Listar / buscar conversas (use `lionchat_conversations_list`)
+
+Combine os filtros conforme o pedido do usuário:
+
+| Usuário pede | Parâmetros |
+|---|---|
+| Conversas abertas | `status: 'open'` (já é o padrão) |
+| Mais recentes / últimas | `sort_by: 'last_activity_at_desc'` (padrão) |
+| Últimas criadas | `sort_by: 'created_at_desc'` |
+| Mais antigas | `sort_by: 'created_at_asc'` |
+| **Não lidas** | `conversation_type: 'unread'` |
+| **Não atendidas** (sem 1ª resposta) | `conversation_type: 'unattended'` |
+| Minhas conversas | `assignee_type: 'me'` |
+| Sem dono / não atribuídas | `assignee_type: 'unassigned'` |
+| Esperando há mais tempo | `sort_by: 'waiting_since_desc'` |
+| Por prioridade | `sort_by: 'priority_desc'` |
+| Todas (qualquer status) | `status: 'all'` |
+
+Notas:
+- Para SÓ a contagem (sem listar), use `lionchat_conversations_meta` com os mesmos filtros (ex: `conversation_type: 'unread'` conta as não lidas).
+- **Não existe filtro nativo de "lidas".** Para isso, liste e considere lidas as conversas com `unread_count == 0` no payload.
+- `lionchat_conversations_unread` é AÇÃO DE ESCRITA (marca como não lida) — NÃO use para buscar.
 
 ### Ver mensagens de uma conversa
 ```
@@ -139,10 +161,25 @@ lionchat_conversations_messages_list (conversation_id: 123)
 ```
 
 ### Criar card Kanban a partir de uma conversa
-```
-1. lionchat_kanban_v2_create (account_id, funnel_id, contact_id, conversation_id, stage)
+
+Use `lionchat_kanban_items_create`. NÃO existem campos `contact_id`/`conversation_id`/`stage` — o contato vem pela conversa vinculada (`conversation_display_id`) e a etapa é o slug em `funnel_stage`.
+
+```json
+POST /api/v1/accounts/{account_id}/kanban_items
+{
+  "kanban_item": {
+    "funnel_id": 12,
+    "funnel_stage": "novo-lead",
+    "position": 0,
+    "item_details": { "title": "Negociação — Fulano" },
+    "conversation_display_id": 123
+  }
+}
 ```
 
+- `conversation_display_id` é **opcional** (card sem conversa vinculada é válido).
+- Ignore as ferramentas `lionchat_kanban_v2_*` — apontam para controllers inexistentes.
+
 ### Relatório de produtividade
 ```
 1. lionchat_reports_summary (visão geral)
@@ -180,13 +217,44 @@ lionchat_conversations_messages_list (conversation_id: 123)
 | Rate limit escrita | 600/min por token |
 | Loop detection | bloqueia chamada idêntica >10x em 10s |
 
-## 7. Quando NÃO chamar nenhuma ferramenta
+## 7. Confirmar antes de agir — regra de ouro
+
+Antes de QUALQUER ação que escreve, modifica, apaga ou envia, pare e avalie se o pedido está claro e completo. Na dúvida, pergunte — **nunca chute**.
+
+**Sempre confirme em linguagem natural (resumindo o efeito) antes de executar quando:**
+
+- **(a) A ação é destrutiva/irreversível** — qualquer `*_destroy`, `*_bulk_actions`, apagar contato (cascateia para as conversas dele), mudar status em massa.
+- **(b) Envia mensagem ao cliente final** — `lionchat_conversations_messages_create` com `message_type` outgoing, `*_scheduled_messages_*`, templates WhatsApp, campanhas/disparos.
+- **(c) Altera config** — conta, inbox, funil, automação, IA Agente (`captain_assistants_update`).
+- **(d) O pedido é ambíguo/incompleto** — falta ID, período, canal, destinatário, ou há mais de uma interpretação possível.
+
+**Como confirmar:** descreva o efeito em linguagem do usuário e aguarde o "sim". Ex.: *"Vou apagar o contato #312 — isso remove as 4 conversas dele também. Confirma?"*. Se faltar dado, peça só o que falta (1-2 perguntas), nunca um questionário.
+
+**Aja sem perguntar apenas em operações idempotentes:** leitura, busca, resumo, classificaçã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.
+
+## 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.
+
+| Intenção do usuário | Tool certa | Cuidado |
+|---|---|---|
+| Listar / ver não lidas | `lionchat_conversations_list` (`conversation_type: 'unread'`) ou `lionchat_conversations_meta` | NÃO use `lionchat_conversations_unread` — é AÇÃO DE ESCRITA (marca como não-lida) |
+| Buscar por texto (nome, telefone, conteúdo) | `lionchat_conversations_search` / `lionchat_contacts_search` | NÃO baixe tudo com `*_list` e filtre na mão |
+| Só a contagem / números | `lionchat_conversations_meta` / `lionchat_reports_summary` | Não liste o conteúdo completo |
+| Criar contato | `lionchat_contacts_create` base (path `/contacts`) | NÃO use as variantes `_1` … `_9` |
+| Pausar a IA agora (botão de pânico) | `lionchat_captain_assistants_update` (`paused: true`, top-level) | — |
+| Anexar arquivo a uma mensagem | `lionchat_upload_create` primeiro, depois usar o retorno em `lionchat_conversations_messages_create` | — |
+| Marcar conversa como **lida** | `lionchat_conversations_update_last_seen` | NÃO use `unread` (esse marca como NÃO-lida) |
+
+## 9. 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)
+## 10. Resources disponíveis (leia sob demanda)
 
 Quando precisar de detalhes profundos, leia um destes documents via `resources/read`:
 
@@ -201,7 +269,7 @@ Quando precisar de detalhes profundos, leia um destes documents via `resources/r
 - `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)
+## 11. Prompts pré-prontos (workflows automatizados)
 
 O usuário pode invocar via slash command (`/nome_do_prompt`):
 
@@ -228,7 +296,7 @@ Quando o cliente pedir pra criar um fluxo:
 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
+## 12. 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)"
@@ -237,7 +305,7 @@ Sempre responda em **PT-BR**. Quando mencionar termos técnicos padronizados da
 
 Isso ajuda o usuário a casar o que você diz com a API/documentação.
 
-## 11. Quando errar uma chamada
+## 13. 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

package/dist/docs/prompts/customer_health.json

@@ -9,5 +9,5 @@
       "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)."
+  "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_1` — GET /contacts/{id}/conversations — passando o `id` do contato):\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/inactive_contacts.json

@@ -19,5 +19,5 @@
       "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)"
+  "template": "Identifique contatos da conta que estão inativos há {{days_inactive|30}} dias ou mais.\n\nComo buscar (use `lionchat_contacts_filter`):\n- Atributo `last_activity_at` com operador `days_before` e valor `{{days_inactive|30}}` — retorna contatos cuja última atividade foi há {{days_inactive|30}}+ dias\n- Para excluir labels, adicione condição `labels` com operador `not_equal_to` pra cada label em {{exclude_labels|none}}\n- Combine as condições com query_operator `and`\n\nCritérios adicionais (filtre o resultado):\n- Tiveram pelo menos {{min_past_conversations|1}} conversa(s) anteriormente (mostra que já são leads ativos, não desconhecidos) — confira via `lionchat_contacts_list_1` (GET /contacts/{id}/conversations) por contato\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/productivity_report.json

@@ -9,5 +9,5 @@
       "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"
+  "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\n   - ATENÇÃO: o relatório por agente NÃO traz CSAT médio nem status online. Pegue o CSAT por agente separadamente: `lionchat_csat_list` filtrando por `user_ids` (id do agente) no mesmo período e calcule a média das notas dele.\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/team_load_balance.json

@@ -14,5 +14,5 @@
       "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."
+  "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) — NÃO vem do relatório por agente; pegue via `lionchat_csat_list` filtrando por `user_ids` (id do agente) no período\n6. Status atual: online / offline / busy — NÃO vem do relatório por agente; pegue via `lionchat_agent_availability_list`\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/resources/api-conventions.md

@@ -124,8 +124,16 @@ A KEY é o slug interno (`novo_lead`). O `name` é o que aparece na UI ("Novo Le
 
 ### Query params padrão
 
-- `page` (int, 1-indexado, default 1)
-- `per_page` (int, default varia por endpoint, máximo 100 clamp server-side)
+- `page` (int, 1-indexado, default 1) — **sempre respeitado**
+- `per_page` (int, máximo 100 clamp server-side) — **page-size é por-endpoint e às vezes FIXO**
+
+> **Atenção: vários endpoints IGNORAM `per_page` e usam um tamanho fixo.** Exemplos confirmados:
+> - **Conversas** (`conversations_list`): 25 fixo (`CONVERSATION_RESULTS_PER_PAGE`, default 25) — `per_page` é ignorado.
+> - **Contatos** (`contacts_list`): 15 fixo (`RESULTS_PER_PAGE = 15`) — `per_page` é ignorado.
+> - **Busca de mensagens** (`messages_search`): 20 fixo.
+>
+> Nesses casos, NÃO confie em `per_page` pra trazer 100 de uma vez — pagine via `page`
+> (`page=1`, `page=2`, ...) e use `meta.total_count` pra saber quando parar.
 
 ### Resposta típica
 
@@ -156,7 +164,7 @@ Ou para listas grandes (cursors):
 
 ### Estratégia recomendada
 
-- Para listar tudo: **NÃO** itere infinitamente. Sempre limite (`per_page=100` + 1 página é geralmente suficiente).
+- Para listar tudo: **NÃO** itere infinitamente. Quando o endpoint respeita `per_page`, `per_page=100` + 1 página é geralmente suficiente. Quando o page-size é FIXO (conversas=25, contatos=15, busca de msg=20), pagine por `page` e pare ao bater `meta.total_count`.
 - Para "quantos X tem": prefira endpoints `meta` ou `count`.
 - Para encontrar X específico: prefira `search` ou `filter` (server-side).
 

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

@@ -21,7 +21,7 @@ A maioria dos endpoints aceita parâmetros pra filtrar antes de retornar:
 |---|---|
 | `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` |
+| `messages_search` | `q`, `file_type[]`, `private_only`, `page` (busca dentro de UMA conversa) |
 | `kanban_items_list` | `funnel_id`, `funnel_stage`, `assigned_agent_id` |
 | `reports_list_*` | `since`, `until`, `metric`, `type` |
 
@@ -64,8 +64,12 @@ Quando existir endpoint específico, prefira:
 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)
+2. Se precisa contexto: pegue só as últimas 20-30 mensagens com `conversations_messages_list` (use `page`)
+3. Pra análise/resumo completo, use `conversations_messages_list` paginando — é a fonte do texto.
+
+> **Atenção:** `conversations_transcript` NÃO retorna o texto da conversa pra você ler. Ele EXIGE o
+> parâmetro `email` e apenas dispara um e-mail (via `ConversationReplyMailer`) com a transcrição —
+> responde `head :ok`, sem corpo. Para LER ou RESUMIR uma conversa, use `conversations_messages_list`.
 
 ## Operações em massa
 
@@ -78,9 +82,10 @@ 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
+LionChat tem rate limit por API token (fonte única: `api-conventions.md` → seção Rate Limiting):
+- 1200 req/min para leitura (reads)
+- 600 req/min para escrita (writes)
+- Detecção de loop: 10 chamadas idênticas em 10 seg
 
 Se receber `429 Too Many Requests`:
 - Espere o `Retry-After` header
@@ -157,6 +162,15 @@ Nunca hard-code esses dados em respostas geradas.
 2. `reports_list_*` (agent_overview) com `since=7d_ago`, `until=now`
 3. Sintetize: agente X com Y resoluções, tempo médio Z
 
+### "Enviar mensagem com anexo (imagem/arquivo)"
+1. `upload_create` (a partir de arquivo OU de uma URL) → resposta traz `file_url` e `blob_id`
+2. `conversations_messages_create` passando o `blob_id` (signed_id) dentro do array `attachments`:
+   ```json
+   { "content": "Segue o documento", "message_type": "outgoing", "attachments": ["<blob_id>"] }
+   ```
+   Cada item de `attachments` é o `blob_id` retornado pelo upload. Pode mandar vários.
+3. O mesmo padrão vale pra anexar mídia num card do Kanban (use o `blob_id` no campo de anexo do card).
+
 ## Cuidados com tools de criação
 
 Endpoints `create_*` modificam dados reais. Antes de chamar:
@@ -164,6 +178,26 @@ Endpoints `create_*` modificam dados reais. Antes de chamar:
 - Verifique se o recurso já existe (evite duplicatas)
 - Use `dry_run` quando disponível
 
+### Wrappers de body obrigatórios (exceções à regra "use raiz")
+
+A regra geral é mandar o body na raiz (ver `api-conventions.md`). Mas três endpoints usam
+`params.require(...)` no controller e **exigem o wrapper nomeado** — sem ele dá `400`/`422`:
+
+| Tool | Wrapper obrigatório | Controller |
+|---|---|---|
+| `companies_create` / `companies_update` | `{ "company": { ... } }` | `params.require(:company)` |
+| `canned_responses_create` | `{ "canned_response": { ... } }` | `params.require(:canned_response)` |
+| `scheduled_messages_create` (dentro de conversa) | `{ "scheduled_message": { ... } }` | `params.require(:scheduled_message)` |
+
+Exemplo:
+
+```json
+{ "company": { "name": "Acme", "domain": "acme.com" } }
+```
+
+> Observação: o endpoint `scheduled_messages` de nível raiz (fora de conversa) usa `params.permit`
+> sem wrapper. A exigência de wrapper vale para o criar-dentro-da-conversa.
+
 ## Erros comuns a evitar
 
 | Erro | Como evitar |

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

@@ -195,6 +195,102 @@ Conversation
 2. Tem SLA policy ativando state change?
 3. Veio de external API call?
 
+## Receitas de ação (qual tool usar pra cada coisa)
+
+### ENVIAR MENSAGEM (`conversations_messages_create`)
+
+Endpoint: `POST /api/v1/accounts/{account_id}/conversations/{conversation_id}/messages`
+Os campos vão na **raiz** do payload (NÃO há wrapper). Construídos pelo `Messages::MessageBuilder`.
+
+**Payload mínimo (resposta de texto pro cliente):**
+```json
+{
+  "content": "Olá! Como posso ajudar?",
+  "message_type": "outgoing"
+}
+```
+
+**Campos:**
+
+| Campo | Obrigatório | Detalhe |
+|---|---|---|
+| `content` | sim* | Texto da mensagem (*pode ser vazio se houver `attachments`) |
+| `message_type` | recomendado | `outgoing` (padrão, resposta do agente) ou `incoming`. **`incoming` SÓ é permitido em inbox do tipo API** — em outros canais levanta erro |
+| `private` | não | `true` = nota interna (só agentes veem, não vai pro cliente). Default `false` |
+| `attachments` | não | Array de arquivos (upload) ou `signed_id` (ActiveStorage). Escolhe endpoint de mídia pelo MIME |
+| `content_attributes.in_reply_to` | não | ID da mensagem que está sendo respondida/citada |
+| `template_params` | não | Parâmetros de template WhatsApp (header/body/buttons). JSON |
+| `cc_emails` / `bcc_emails` / `to_emails` | não | SÓ em inbox Email. Lista separada por vírgula |
+
+**Nota interna (não vai pro cliente):**
+```json
+{ "content": "Cliente parece irritado, tratar com cuidado", "private": true }
+```
+
+### AÇÃO → TOOL (mapa rápido)
+
+NÃO confunda com `conversations_update`: o update só altera **prioridade** e **IA Agente**
+(`captain_assistant_id`). Para mudar status, prioridade ou atribuição use as tools abaixo.
+
+| Ação desejada | Tool / endpoint | Parâmetros |
+|---|---|---|
+| Resolver conversa | `toggle_status` (POST `.../toggle_status`) | `status: "resolved"` |
+| Reabrir conversa | `toggle_status` | `status: "open"` |
+| Marcar como pendente | `toggle_status` | `status: "pending"` |
+| Adiar (snooze) | `toggle_status` | `status: "snoozed"` + `snoozed_until` (datetime futuro) |
+| Mudar prioridade | `toggle_priority` (POST `.../toggle_priority`) | `priority`: `urgent`/`high`/`medium`/`low`/`nil` |
+| Atribuir agente | `assignments` (POST `.../assignments`) | `assignee_id` |
+| Atribuir time | `assignments` | `team_id` |
+| Ativar/trocar IA Agente | `conversations_update` (PATCH) | `captain_assistant_id` |
+| Desativar IA Agente | `conversations_update` (PATCH) | `captain_assistant_id: 0` (ou null) |
+
+**IMPORTANTE:** `conversations_update` (PATCH) só aceita `priority` e `captain_assistant_id`
+(ver `permitted_update_params`, conversations_controller.rb). Mandar `status` no update **não muda
+o status** — é ignorado. Use sempre `toggle_status` para status.
+
+**Snooze exige `snoozed_until`:**
+```json
+POST .../conversations/{id}/toggle_status
+{ "status": "snoozed", "snoozed_until": "2026-06-01T09:00:00Z" }
+```
+
+### MARCAR COMO LIDA vs NÃO-LIDA
+
+| Ação | Tool / endpoint | Efeito |
+|---|---|---|
+| Marcar como **lida** | `update_last_seen` (POST `.../update_last_seen`) | Atualiza `agent_last_seen_at`; em canal WAHA dispara check azul no WhatsApp |
+| Marcar como **não-lida** | `conversations_unread` (POST `.../unread`) | Recua o `last_seen` pra antes da última mensagem do cliente — conversa volta a aparecer como não-lida |
+
+Ambas são **ações de escrita** (POST). `unread` é o oposto de `update_last_seen`, não uma consulta.
+
+### AGENDAR MENSAGEM (`scheduled_messages_create`)
+
+Endpoint: `POST /api/v1/accounts/{account_id}/conversations/{conversation_id}/scheduled_messages`
+
+**ATENÇÃO:** diferente do padrão "raiz" das mensagens normais, aqui o payload **EXIGE o wrapper**
+`scheduled_message` (`params.require(:scheduled_message)`).
+
+**Payload:**
+```json
+{
+  "scheduled_message": {
+    "content": "Lembrete: sua consulta é amanhã às 14h",
+    "scheduled_at": "2026-06-01T14:00:00Z",
+    "inbox_id": 12
+  }
+}
+```
+
+| Campo | Obrigatório | Detalhe |
+|---|---|---|
+| `content` | sim | Texto a enviar |
+| `scheduled_at` | sim | Quando enviar (datetime) |
+| `inbox_id` | sim | Caixa de entrada por onde sair |
+| `is_recurrent` | não | `true` ativa recorrência |
+| `period` | não | Período da recorrência (ex.: `daily`, `weekly`) — vira `{ type: ... }` |
+| `recurrence_count` | não | Quantas vezes repetir |
+| `template_params` | não | Parâmetros de template WhatsApp |
+
 ## Eventos importantes (pra automation)
 
 | Evento | Quando dispara |

package/dist/docs/resources/data-model.md

@@ -145,6 +145,10 @@ Company
 └── domain
 ```
 
+**`additional_attributes` vs `custom_attributes` no Contato:**
+- `additional_attributes` (jsonb): campos do sistema porém **EDITÁVEIS via API** (`permitted_params` permite `additional_attributes: {}`). Guarda chaves padrão como `city`, `company`, `country_code` — que são as chaves filtráveis em `lib/filters/filter_keys.yml` (tipo `additional_attributes`). NÃO é não-editável.
+- `custom_attributes` (jsonb): dado de negócio livre, definido pelo cliente via Atributos Customizados.
+
 **Padrões de `source_id` por canal:**
 - Waha: `5511999999999@c.us` (1-on-1) ou `120363xxx@g.us` (grupo) ou `XXXX@lid` (LID)
 - WhatsApp Cloud: `5511999999999` (E.164 sem prefixo)
@@ -272,12 +276,22 @@ Macro
 AccountTask (agenda interna)
 ├── id (PK)
 ├── account_id (FK)
-├── user_id (FK → User, assignee)
+├── user_id (FK → User, optional)
+├── created_by (FK → User)
 ├── title
 ├── description
-├── due_at (datetime)
-├── completed_at (datetime, nullable)
-└── color (string)
+├── task_type (string: task/follow_up/call/meeting/video_call/deadline/custom)
+├── priority (string: none/low/medium/high/urgent)
+├── status (enum: pending=0 (default) / completed=1 / cancelled=2 / snoozed=3)
+├── scheduled_at (datetime) — data/hora da tarefa
+├── duration_minutes (int, default por task_type: task/follow_up=15, call=30, meeting/video_call=60)
+├── snoozed_until (datetime, se status=snoozed)
+├── recurrence_type (string nullable: daily/weekly/biweekly/monthly/yearly; nil = tarefa única)
+├── recurrence_count (int nullable, 1-365)
+├── meeting_url (string, sala de reunião call/meeting)
+├── guest_emails (jsonb array, convidados extras — máx 20)
+├── conversation_id / contact_id / linked_kanban_item_id (FK opcionais)
+└── assignees (has_many → User, via account_task_assignments)
 
 BookingEventType (template de agendamento)
 ├── id (PK)