# Listar conversas Lista as conversas que você vê, filtradas pela data em que a conversa começou (dias inteiros em America/Sao_Paulo), por caixa, situação e etiqueta, em ordem de início (o número da conversa). Até 200 por chamada; use o cursor `proximo` para continuar com os mesmos filtros, enquanto houver `proximo`. Uma página pode trazer menos conversas que o limite. Ler · Leitura Nome da ferramenta: ``` conversas_listar ``` ## Exemplo de pedido Você escreve para o agente, em linguagem natural: > Quantas conversas novas chegaram pelo WhatsApp na semana passada? ## Permissão - Só lê, não muda nada na Eloquus. - Pede o escopo Ler (`eloquus:ler`), que vem sempre marcado na conexão. - Área da Eloquus: Conversas. ## Parâmetros | Nome | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `conta` | texto | Sim | A conta da Eloquus (slug). contas_listar mostra as suas. | | `caixa` | número inteiro | Não | Id da caixa de entrada (caixas_listar). Aceita: a partir de 1 | | `status` | texto | Não | Situação; all (padrão) traz todas. Aceita: open, pending, resolved, snoozed, all | | `etiqueta` | texto | Não | Aceita: de 1 a 60 caracteres | | `desde` | texto | Sim | Começo do período: AAAA-MM-DD (dia inteiro em America/Sao_Paulo) ou data e hora ISO com fuso. Aceita: de 10 a 40 caracteres | | `ate` | texto | Sim | Fim do período (incluído): AAAA-MM-DD (dia inteiro em America/Sao_Paulo) ou data e hora ISO com fuso. Aceita: de 10 a 40 caracteres | | `limite` | número inteiro | Não | Padrão 50. Aceita: de 1 a 200 | | `cursor` | texto | Não | O `proximo` da resposta anterior, com os mesmos filtros. Aceita: de 1 a 200 caracteres | ## Paginação A resposta traz `proximo` quando há mais itens. Para continuar, chame de novo com os mesmos filtros e `cursor` igual ao `proximo` recebido, até ele vir vazio. ## Limites - 120 chamadas por minuto por conexão e 600 por minuto por conta, somando todos os agentes conectados. ## Detalhes técnicos **Pedido JSON-RPC (tools/call)** Com só os campos obrigatórios e valores de exemplo. ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "conversas_listar", "arguments": { "conta": "nome-da-sua-conta", "desde": "2026-11-01", "ate": "2026-11-01" } } } ``` **Esquema de entrada** ```json { "type": "object", "properties": { "conta": { "type": "string", "description": "A conta da Eloquus (slug). contas_listar mostra as suas." }, "caixa": { "type": "integer", "minimum": 1, "description": "Id da caixa de entrada (caixas_listar)." }, "status": { "type": "string", "enum": [ "open", "pending", "resolved", "snoozed", "all" ], "description": "Situação; all (padrão) traz todas." }, "etiqueta": { "type": "string", "minLength": 1, "maxLength": 60 }, "desde": { "type": "string", "minLength": 10, "maxLength": 40, "description": "Começo do período: AAAA-MM-DD (dia inteiro em America/Sao_Paulo) ou data e hora ISO com fuso." }, "ate": { "type": "string", "minLength": 10, "maxLength": 40, "description": "Fim do período (incluído): AAAA-MM-DD (dia inteiro em America/Sao_Paulo) ou data e hora ISO com fuso." }, "limite": { "type": "integer", "minimum": 1, "maximum": 200, "description": "Padrão 50." }, "cursor": { "type": "string", "minLength": 1, "maxLength": 200, "description": "O `proximo` da resposta anterior, com os mesmos filtros." } }, "required": [ "conta", "desde", "ate" ], "additionalProperties": false } ``` **Esquema da resposta** ```json { "type": "object", "additionalProperties": false, "properties": { "conversas": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "integer" }, "contato": { "type": "object", "additionalProperties": false, "properties": { "id": { "description": "Id do contato. Pode ser null." }, "nome": { "type": "string" } }, "required": [ "id", "nome" ] }, "caixa": { "type": "integer" }, "status": { "description": "open, pending, resolved ou snoozed. Pode ser null." }, "responsavel": { "description": "Nome de quem atende. Pode ser null." }, "etiquetas": { "type": "array", "items": { "type": "string" } }, "criadaEm": { "type": "string" }, "ultimaAtividadeEm": { "description": "ISO. Pode ser null." }, "ultimaMensagem": { "type": "string" } }, "required": [ "id", "contato", "caixa", "status", "responsavel", "etiquetas", "criadaEm", "ultimaAtividadeEm", "ultimaMensagem" ] } }, "proximo": { "description": "Cursor da próxima página, ou null quando acabou." }, "aviso": { "type": "string", "description": "Só quando a página veio vazia com `proximo`." } }, "required": [ "conversas", "proximo" ] } ```