ibot_list_chats
Lists and filters WhatsApp chats from the I-Bot panel, supporting device, status, tag, unread, and other filters. Returns chat details with pagination control and ceiling alerts.
Instructions
Lista e filtra chats do painel I-Bot. Usa a API interna do painel (sem navegador, ~1s; 250 chats em 1,8s) e cai no Playwright se ela falhar. Filtra por APARELHO (padrão: IBOT_DEVICE; vazio = todos), status, não lidas, arquivados, favoritos, tag, nome e número. Retorna nome, status, tags, aparelho, última mensagem, timestamp e não lidas. O retorno SEMPRE diz qual corte ocorreu (fim real da lista / teto do painel / limite pedido) — nunca corta em silêncio. TETO: a API interna PAGINA (medido 17/08/2026: 250 chats distintos numa consulta), mas o Playwright de fallback trava em 100 POR CONSULTA sem paginação (medido 14/08/2026: nenhum limit/offset traz o chat 101) — se o retorno avisar teto do painel, varrer além exige FATIAR por filtro e cruzar wa_chat_id. FORÇA DOS EIXOS, medida em produção: device é o mais forte (cada aparelho é uma janela própria; único jeito de isolar o inbound de UM número) > department (que é TAG, uma janela por tag) > status × order_by, que satura rápido — cruzar 6 status × 8 ordenações bate o teto em quase toda fatia e deixa um MIOLO inalcançável. Três armadilhas medidas: (1) whatsapp_number dá FALSO NEGATIVO — o chat existe, wa_chat_id igual ao buscado, e a busca volta vazia; a causa é o filtro de arquivados ser EXCLUSIVO (numa conta madura quase todo o histórico está arquivado), e leads já foram dados como 'sem chat' tendo chat ABERTO. Pela API interna isso está resolvido (busca por número que não acha nada refaz o pass entre arquivados e avisa), mas no fallback Playwright a armadilha continua: nunca conclua 'não tem chat' sem repetir com archived=true; (2) a ordenação padrão é por última mensagem, que AFUNDA o chat sem resposta (a última mensagem é a do cliente, antiga) — para caçar conversa parada sem dono use '-created', e para achar quem nem isso alcança use 'updated' (ascendente), que foi o que revelou leads invisíveis a 4 ciclos de varredura; (3) o nome do contato aqui é o do WhatsApp, não o do CRM ('.', '', nome de empresa) — buscar pelo nome que está no CRM dá falso negativo. SEMPRE rode um controle positivo (um chat de estado já conhecido) na mesma virada: sem ele não há como distinguir 'não existe' de 'a fatia não alcança'.
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "ibot_list_chats"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Filtrar por nome do contato (busca parcial). | |
| limit | No | Máximo de chats a retornar (padrão: 50, máximo: 1000). Acima de 100 o scroll precisa carregar mais lotes: conte ~2s a cada 100. | |
| device | No | Filtrar pelo APARELHO (número de origem) que recebe o chat. Padrão: IBOT_DEVICE; vazio ('') lista de TODOS os aparelhos. Aceita trecho do rótulo (ex.: 'comercial', os últimos dígitos do número) ou o id bruto do aparelho. É o corte mais forte que o painel oferece — o mesmo número pode existir em dois aparelhos com conversas DIFERENTES, e no Playwright cada aparelho é uma janela própria de 100. Não casou = ERRO explícito com a lista real de aparelhos, nunca lista sem filtro se passando por lista filtrada. | |
| offset | No | Quantos chats descartar do início da lista (padrão: 0). Use com limit para paginar uma varredura grande sem reprocessar o mesmo trecho. | |
| status | No | Filtrar por status do chat. | |
| archived | No | Se true, retorna SÓ os arquivados (o filtro do I-Bot é exclusivo, não soma com os ativos). | |
| order_by | No | Ordenação. Padrão: -updated (mais recentes). Use -new_messages para ordenar por não lidas. | |
| favorited | No | Se true, mostra apenas chats favoritados. | |
| department | No | ATENÇÃO — este filtro é de TAG, não de departamento (os labels de checkbox do painel são todos tags, ex.: 'Lead Quente', 'Cliente | Plano Gold'). O nome do parâmetro é herança e engana; para filtrar por departamento de verdade use `responsavel`. Vale como eixo de fatiamento: cada tag é uma janela própria de 100. Não casou = ERRO explícito com as tags disponíveis. | |
| responsavel | No | Filtrar por QUEM está com o chat — é o dropdown 'Usuário/Departamento' do painel. Aceita vários de uma vez (regra OU: devolve chat de qualquer um da lista), misturando PESSOA e DEPARTAMENTO livremente, porque no painel os dois vivem no mesmo seletor. Ex: ["Maria Souza", "Financeiro"]. Aceita nome completo, parte do nome, e-mail ou o id. Use ["sem responsável"] para os chats que NINGUÉM pegou — é o eixo pra caçar conversa órfã, e combina bem com order_by='-created'. Nome que não existe ou que casa com mais de um = ERRO explícito com a lista real, nunca lista sem filtro se passando por filtrada. NÃO funciona no fallback Playwright: se a API do painel estiver fora, a tool devolve erro em vez de lista sem esse filtro. | |
| unread_only | No | Se true, mostra apenas chats com mensagens não lidas. | |
| whatsapp_number | No | Filtrar por número WhatsApp (ex: 5511999990000). |