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.
conversas_listarExemplo 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.
{
"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
{
"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
{
"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"
]
}