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'.
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). |