> ## Documentation Index > Fetch the complete documentation index at: https://docs.wppfy.com/llms.txt > Use this file to discover all available pages before exploring further. # Busca chats com filtros > Busca chats com diversos filtros e ordenação. Suporta filtros em todos os campos do chat, paginação e ordenação customizada. Operadores de filtro: - `=` : igualdade exata - `~` : LIKE (contém) - `!~` : NOT LIKE (não contém) - `!=` : diferente - `>=` : maior ou igual - `>` : maior que - `<=` : menor ou igual - `<` : menor que - Sem operador: LIKE (contém) Na API 2.3.0, o formato completo preserva o contrato legado: padrão de 2000 registros e limit positivo explícito sem o novo teto de 500. Com compact=true, o padrão é 100 e o máximo é 200; nesse modo, limites maiores são reduzidos pelo servidor. Valores de limit omitidos, zero ou negativos usam o padrão do modo. Prefira o formato compacto e paginação explícita nas novas integrações. A projeção compacta usa os mesmos nomes JSON, omitindo campos de detalhes, notas, campos customizados e estado do chatbot. Ela inclui `lead_awaitingReply`. Filtros podem usar campos não incluídos na projeção. A resposta mantém chats, totalChatsStats e pagination. O atalho de busca por identificador pode retornar paginação { totalRecords: 1, limit: 1, offset: 0 }. ## OpenAPI ````yaml /openapi-pt-BR.json post /chat/find openapi: 3.1.0 info: title: WppFy - WhatsApp API version: 1.0.0 description: > API para gerenciamento de instâncias do WhatsApp e comunicações. ## Recomendação Importante: WhatsApp Business **É ALTAMENTE RECOMENDADO usar contas do WhatsApp Business** em vez do WhatsApp normal para integração, o WhatsApp normal pode apresentar inconsistências, desconexões, limitações e instabilidades durante o uso com a nossa API. ## Autenticação - Endpoints regulares requerem um header 'token' com o token da instância ## Estados da Instância As instâncias podem estar nos seguintes estados: - `disconnected`: Desconectado do WhatsApp - `connecting`: Em processo de conexão - `connected`: Conectado e autenticado com sucesso servers: - url: https://api.wppfy.com security: - token: [] tags: - name: Instancia description: | Operações relacionadas ao ciclo de vida de uma instância, como conectar, desconectar e verificar o status. - name: Proxy description: > A WppFy opera com um proxy interno como padrão. Você pode manter esse padrão, configurar um proxy próprio via `proxy_url` ou usar seu celular android como proxy instalando o app em https://github.com/WppFy/silver_proxy_apk (APK direto: https://github.com/WppFy/silver_proxy_apk/raw/refs/heads/main/silver_proxy.apk). Se nada for enviado, seguimos no proxy interno. IPs são brasileiros; para clientes internacionais, considere um proxy da região do cliente. - name: Perfil description: | Operações relacionadas ao perfil da instância do WhatsApp, como alterar nome e imagem de perfil. - name: Business description: | ⚠️ **EXPERIMENTAL** - Endpoints ainda não testados completamente. Operações relacionadas ao perfil comercial do WhatsApp Business. Permite consultar e atualizar dados do perfil comercial como descrição, endereço, email, categorias e gerenciar o catálogo de produtos. **Requisitos:** - A conta atualmente conectada deve ser uma conta **WhatsApp Business** - Contas pessoais do WhatsApp não possuem perfil comercial **Nota:** Estes endpoints podem não funcionar como esperado. Reporte problemas encontrados. - name: Chamadas description: | Operações relacionadas a chamadas peloWhatsApp. Permite realizar e rejeitar chamadas programaticamente. - name: Enviar Mensagem description: > Endpoints para envio de mensagens do WhatsApp com diferentes tipos de conteúdo. ## Campos Opcionais Comuns Todos os endpoints de envio de mensagem suportam os seguintes campos opcionais: - **`delay`** *(integer)*: Atraso em milissegundos antes do envio - Durante o atraso aparecerá "Digitando..." ou "Gravando áudio..." dependendo do tipo - Exemplo: `5000` (5 segundos) - **`readchat`** *(boolean)*: Marcar chat como lido após envio - Remove o contador de mensagens não lidas do chat - Exemplo: `true` - **`readmessages`** *(boolean)*: Marcar últimas mensagens recebidas como lidas - Marca as últimas 10 mensagens **recebidas** (não enviadas por você) como lidas - Útil para confirmar leitura de mensagens pendentes antes de responder - Diferente do `readchat` que apenas remove contador de não lidas - Exemplo: `true` - **`replyid`** *(string)*: ID da mensagem para responder - Cria uma resposta vinculada à mensagem original - Suporte varia por tipo de mensagem - Exemplo: `"3A12345678901234567890123456789012"` - **`mentions`** *(string)*: Números para mencionar (apenas para envio em grupos) - Números específicos: `"5511999999999,5511888888888"` - Mencionar todos: `"all"` - **`forward`** *(boolean)*: Marca a mensagem como encaminhada no WhatsApp - Adiciona o indicador "Encaminhada" na mensagem - Exemplo: `true` - **`track_source`** *(string)*: Origem do rastreamento da mensagem - Identifica o sistema ou fonte que está enviando a mensagem - Útil para integrações (ex: "chatwoot", "crm", "chatbot") - Exemplo: `"chatwoot"` - **`track_id`** *(string)*: ID para rastreamento da mensagem - Identificador livre para acompanhar a mensagem em sistemas externos - Permite correlacionar mensagens entre diferentes plataformas - **Nota**: O sistema aceita valores duplicados - não há validação de unicidade - Use o mesmo ID em várias mensagens se fizer sentido para sua integração - Exemplo: `"msg_123456789"` ### Envio para Grupos - **`number`** *(string)*: Para enviar mensagem para grupo, use o ID do grupo que termina com `@g.us` - Exemplo: `"120363012345678901@g.us"` - **Como obter o ID do grupo:** - Use o `chatid` do webhook recebido quando alguém envia mensagem no grupo - Use o endpoint `GET /group/list` para listar todos os grupos e seus IDs ## Placeholders Disponíveis Todos os endpoints de envio de mensagem suportam placeholders dinâmicos para personalização automática: ### Campos de Nome - **`{{name}}`**: Nome consolidado do chat, usando a primeira opção disponível: 1. Nome do lead (`lead_name`) 2. Nome completo do lead (`lead_fullName`) 3. Nome do contato no WhatsApp (`wa_contactName`) 4. Nome do perfil do WhatsApp (`wa_name`) - **`{{first_name}}`**: Primeira palavra válida do nome consolidado (mínimo 2 caracteres) ### Campos do WhatsApp - **`{{wa_name}}`**: Nome do perfil do WhatsApp - **`{{wa_contactName}}`**: Nome do contato como salvo no WhatsApp ### Campos do Lead - **`{{lead_name}}`**: Nome do lead - **`{{lead_fullName}}`**: Nome completo do lead - **`{{lead_personalid}}`**: ID pessoal (CPF, CNPJ, etc) - **`{{lead_email}}`**: Email do lead - **`{{lead_status}}`**: Status atual do lead - **`{{lead_notes}}`**: Anotações do lead - **`{{lead_assignedAttendant_id}}`**: ID do atendente designado ### Campos Personalizados Campos adicionados via custom fields são acessíveis usando `{{lead_field01}}` à `{{lead_field20}}` ou usar `{{nomedocampo}}` definido em `/instance/updateFieldsMap`. ### Exemplo de Uso ``` Olá {{name}}! Vi que você trabalha na {{company}}. Seu email {{lead_email}} está correto? ``` **💡 Dica**: Use `/chat/find` para buscar dados do chat e ver os campos disponíveis antes de enviar mensagens com placeholders. - name: Mensagem Async description: > Controles operacionais da fila interna de envio assíncrono usada quando um endpoint de envio recebe `async=true`. Esta seção serve para: - consultar o estado atual da fila async - configurar o delay entre mensagens enviadas com `async=true` - limpar backlog pendente e cancelar mensagens ainda não concluídas Escopo: - cobre apenas a fila interna de mensagens diretas async - não altera mensagens já enviadas com sucesso - name: Ações na mensagem e Buscar - name: Chats - name: Contatos - name: Bloqueios - name: Etiquetas - name: Grupos e Comunidades - name: Newsletters e Canais description: > Operações para leitura e acompanhamento de canais do WhatsApp (newsletters). Casos de uso principais: - listar posts já publicados em um canal - editar posts recentes de um canal - deletar posts recentes de um canal - consultar views e reações dos posts - integrar canais sem necessidade de persistir as mensagens localmente Observações: - `/newsletter/messages` retorna o conteúdo dos posts - `/newsletter/messages/edit` edita o conteúdo de posts recentes - `/newsletter/messages/delete` apaga posts recentes - views (`viewsCount`) e reactions (`reactionCounts`) vêm em cada post de `/newsletter/messages`, não por evento de webhook - `/newsletter/updates` está obsoleta: o WhatsApp não responde e a API devolve 504 - newsletters usam rotas próprias e não devem usar `/message/edit` ou `/message/delete` - name: Respostas Rápidas description: > Gerenciamento de respostas rápidas para agilizar o atendimento. **⚠️ Importante**: Este recurso tem serventia apenas se você utilizar um sistema frontend/interface personalizada para registrar e utilizar as respostas. A API apenas armazena as respostas, mas não as aplica automaticamente. ### Como funciona: - **Criar**: Cadastre respostas pré-definidas com títulos e conteúdo - **Listar**: Recupere todas as respostas cadastradas para exibir na sua interface - **Usar**: Seu sistema frontend pode usar essas respostas para agilizar digitação ### Casos de uso: - Interfaces web personalizadas de atendimento - Apps mobile com sugestões de resposta - Sistemas CRM com templates de mensagem - Ferramentas de produtividade para atendentes **Não é um chatbot**: Para respostas automáticas, use os recursos de Chatbot. - name: CRM description: > Sistema completo de gestão de relacionamento com clientes integrado à API. **💾 Armazenamento interno**: Todos os dados dos leads ficam salvos diretamente na API, eliminando a necessidade de bancos de dados externos. Sua aplicação pode focar apenas na interface e lógica de negócio. ### Recursos disponíveis: - **📋 20+ campos personalizáveis**: Nome, telefone, email, empresa, observações, etc. - **🏷️ Sistema de etiquetas**: Organize e categorize seus contatos - **🔍 Busca avançada**: Filtre por qualquer campo ou etiqueta - **📊 Histórico completo**: Todas as interações ficam registradas automaticamente ### 🎯 Placeholders em mensagens: Use variáveis dinâmicas nas mensagens para personalização automática: ``` Olá {{nome}}! Vi que você trabalha na {{empresa}}. Seu email {{email}} está correto? Observações: {{observacoes}} ``` ### Fluxo típico: 1. **Captura**: Leads chegam via WhatsApp ou formulários 2. **Enriquecimento**: Adicione dados usando `/chat/editLead` 3. **Segmentação**: Organize com etiquetas 4. **Comunicação**: Envie mensagens personalizadas com placeholders 5. **Acompanhamento**: Histórico fica salvo automaticamente **Ideal para**: Vendas, marketing, atendimento, qualificação de leads - name: Integração Chatwoot description: > **🚧 INTEGRAÇÃO BETA - Sistema de integração com Chatwoot para atendimento unificado** **⚠️ AVISO**: Esta integração está em fase BETA. Use por sua conta e risco. Recomendamos testes em ambiente não-produtivo antes do uso em produção. Esta categoria contém recursos para configurar e gerenciar a integração com o Chatwoot, uma plataforma de atendimento ao cliente open-source. A integração permite centralizar conversas do WhatsApp no Chatwoot. ### Recursos disponíveis: - 🔧 **Configuração Completa**: Configure URL, tokens e credenciais do Chatwoot - 📬 **Sincronização Bidirecional**: Mensagens novas entre WhatsApp e Chatwoot são sincronizadas automaticamente - 📱 **Gerenciamento de Contatos**: Sincronização automática de nomes e telefones - 🔄 **Atualização LID→PN**: Migração automática de Local ID para Phone Number - 🏷️ **Nomes Inteligentes**: Sistema de nomes com til (~) para atualização automática - 🚫 **Separação de Grupos**: Opção para ignorar grupos na sincronização - 👤 **Assinatura de Mensagens**: Identificação do agente nas mensagens enviadas - 🔗 **Webhook Automático**: URL gerada automaticamente para configurar no Chatwoot ### 🏷️ Sistema de Nomes Inteligentes: - **Nomes com til (~)**: Atualizados automaticamente quando contato modifica nome no WhatsApp - **Nomes específicos**: Para nome fixo, remover til (~) do nome no Chatwoot - **Exemplo**: "~João Silva" = automático, "João Silva" = fixo - **Migração LID→PN**: Sem duplicação de conversas durante a transição - **Respostas nativas**: Aparecem diretamente no Chatwoot sem marcações externas ### ⚠️ Limitações conhecidas: - **Sincronização de histórico**: Não implementada - apenas mensagens novas são sincronizadas ### Casos de uso: - Atendimento centralizado no Chatwoot - Equipes de suporte com múltiplos agentes - Integração com CRM via Chatwoot - Centralização de canais de comunicação - Gestão automática de contatos e nomes **Ideal para**: Empresas com equipes de atendimento, call centers, suporte técnico (em ambiente de testes) **Requer**: Instância do Chatwoot configurada, tokens de API e ambiente de testes **🚧 Lembre-se**: Integração em BETA - funcionalidades podem mudar sem aviso prévio - name: Server-Sent Events (SSE) paths: /chat/find: post: tags: - Chats summary: Busca chats com filtros description: > Busca chats com diversos filtros e ordenação. Suporta filtros em todos os campos do chat, paginação e ordenação customizada. Operadores de filtro: - `=` : igualdade exata - `~` : LIKE (contém) - `!~` : NOT LIKE (não contém) - `!=` : diferente - `>=` : maior ou igual - `>` : maior que - `<=` : menor ou igual - `<` : menor que - Sem operador: LIKE (contém) Na API 2.3.0, o formato completo preserva o contrato legado: padrão de 2000 registros e limit positivo explícito sem o novo teto de 500. Com compact=true, o padrão é 100 e o máximo é 200; nesse modo, limites maiores são reduzidos pelo servidor. Valores de limit omitidos, zero ou negativos usam o padrão do modo. Prefira o formato compacto e paginação explícita nas novas integrações. A projeção compacta usa os mesmos nomes JSON, omitindo campos de detalhes, notas, campos customizados e estado do chatbot. Ela inclui `lead_awaitingReply`. Filtros podem usar campos não incluídos na projeção. A resposta mantém chats, totalChatsStats e pagination. O atalho de busca por identificador pode retornar paginação { totalRecords: 1, limit: 1, offset: 0 }. requestBody: required: true content: application/json: schema: type: object properties: operator: type: string enum: - AND - OR default: AND description: Operador lógico entre os filtros sort: type: string description: Campo para ordenação (+/-campo). Ex -wa_lastMsgTimestamp limit: type: integer description: >- Formato completo: padrão 2000, preservando limit positivo explícito sem novo teto. Formato compacto: padrão 100, máximo 200. Omitido, zero ou negativo usa o padrão do modo. offset: type: integer description: Número de registros a pular (para paginação) default: 0 compact: type: boolean default: false description: > Retorna somente a projeção usada em listas/sidebar: identidade, nomes, preview, flags, unread, última mensagem, labels e campos essenciais do lead. Não retorna campos customizados, notas completas nem estado do chatbot. wa_fastid: type: string wa_chatid: type: string wa_archived: type: boolean wa_contactName: type: string wa_name: type: string name: type: string wa_isBlocked: type: boolean wa_isGroup: type: boolean wa_isGroup_admin: type: boolean wa_isGroup_announce: type: boolean wa_isGroup_member: type: boolean wa_isPinned: type: boolean wa_unreadCount: type: string description: >- Mensagens não lidas, com operador: `>0` traz as conversas com não lidas. lead_awaitingReply: type: boolean description: >- `true`: conversas em que o contato espera resposta (aguardando você); `false`: as que não esperam. Conversa sem última mensagem não entra em nenhum dos dois. wa_label: type: string description: >- ID da label aplicada ao chat. Use o valor retornado por `/labels`, não o nome da etiqueta. wa_notes: type: string lead_tags: type: string lead_isTicketOpen: type: boolean lead_assignedAttendant_id: type: string lead_status: type: string description: Use `=valor` para igualdade explícita. lead_tag: type: string description: | Retorna chats que contenham exatamente esta tag em `lead_tags`, sem confundir nomes parcialmente iguais. example: operator: AND sort: '-wa_lastMsgTimestamp' limit: 50 offset: 0 wa_isGroup: true lead_status: ~novo lead_tag: vip wa_label: '10' wa_notes: ~vip responses: '200': description: Lista de chats encontrados content: application/json: schema: type: object properties: chats: type: array items: $ref: '#/components/schemas/Chat' description: >- Chats da página. No modo compacto, somente os campos da projeção de listagem são preenchidos. totalChatsStats: type: object description: Contadores totais de chats pagination: type: object properties: totalRecords: type: integer description: Total de registros encontrados limit: type: integer description: Limite aplicado na busca offset: type: integer description: >- Offset retornado, limitado ao intervalo de zero até totalRecords. hasMore: type: boolean description: Há mais registros depois desta página. nextOffset: type: integer description: Offset da próxima página. components: schemas: Chat: type: object description: Representa uma conversa/chamado no sistema properties: id: type: string description: ID único da conversa (r + 7 bytes aleatórios em hex) wa_fastid: type: string description: Identificador rápido do WhatsApp wa_chatid: type: string description: ID completo do chat no WhatsApp wa_chatlid: type: string description: LID do chat no WhatsApp (quando disponível) wa_archived: type: boolean description: Indica se o chat está arquivado default: false wa_contactName: type: string description: > Nome salvo na agenda do celular deste número (vazio: não está salvo). A conversa nasce com ele (por LID, pelo número ligado) e ele muda quando o contato é salvo ou apagado no celular. default: '' wa_name: type: string description: > Nome definido pelo usuário no perfil do WhatsApp ("push name"). Vem do perfil do contato e pode não estar disponível dependendo do contexto ou da origem dos dados. default: '' name: type: string description: > Nome resolvido pelo sistema como fallback. Normalmente consolida o melhor valor disponível entre dados internos, nome vindo do WhatsApp e nome salvo nos contatos. Por isso, costuma ter maior chance de vir preenchido. default: '' image: type: string description: URL da imagem do chat default: '' imagePreview: type: string description: URL da miniatura da imagem default: '' parent_community: type: object description: Comunidade pai do chat quando ele representa um subgrupo properties: jid: type: string format: jid name: type: string image_url: type: string image_preview_url: type: string default_subgroup_jid: type: string format: jid wa_ephemeralExpiration: type: integer format: int64 description: Tempo de expiração de mensagens efêmeras default: 0 wa_isBlocked: type: boolean description: Indica se o contato está bloqueado default: false wa_isGroup: type: boolean description: Indica se é um grupo default: false wa_isGroup_admin: type: boolean description: Indica se o usuário é admin do grupo default: false wa_isGroup_announce: type: boolean description: Indica se é um grupo somente anúncios default: false wa_isGroup_community: type: boolean description: Indica se é uma comunidade default: false wa_isGroup_member: type: boolean description: Indica se é membro do grupo default: false wa_isPinned: type: boolean description: Indica se o chat está fixado default: false wa_label: type: array description: Labels do chat items: type: string wa_notes: type: string description: Anotações internas do chat sincronizadas via app state default: '' wa_lastMessageTextVote: type: string description: Texto/voto da última mensagem default: '' wa_lastMessageType: type: string description: Tipo da última mensagem default: '' wa_lastMsgTimestamp: type: integer format: int64 description: Timestamp da última mensagem default: 0 wa_lastMessageSender: type: string description: Remetente da última mensagem default: '' lead_awaitingReply: type: boolean readOnly: true description: >- `true` quando o contato espera resposta: a última mensagem é dele e ninguém concluiu a conversa (`POST /lead/resolve`). A mensagem do contato liga; a nossa (você, a IA, um fluxo ou uma integração) desliga. Nas conversas anteriores a este campo, a api decide pelo remetente (o número ou o LID da instância). Só em conversas com pessoas: ausente em grupos e canais, que não entram em nenhum dos dois filtros, e quando a conversa não tem última mensagem conhecida (só a data). Filtrável no `/chat/find`. wa_muteEndTime: type: integer format: int64 description: Timestamp do fim do silenciamento default: 0 owner: type: string description: Dono da instância default: '' wa_unreadCount: type: integer format: int64 description: Contador de mensagens não lidas default: 0 phone: type: string description: Número de telefone default: '' common_groups: type: string description: 'Grupos em comum separados por vírgula, formato: (nome_grupo)id_grupo' default: '' example: >- Grupo Família(120363123456789012@g.us),Trabalho(987654321098765432@g.us) lead_name: type: string description: Nome do lead default: '' lead_fullName: type: string description: Nome completo do lead default: '' lead_email: type: string description: Email do lead default: '' lead_personalid: type: string description: Documento de identificação default: '' lead_status: type: string description: Status livre do lead default: '' lead_tags: type: array description: > Tags do lead. Tags configuradas com `kanban=true` também determinam as colunas em que o cartão aparece no Kanban. items: type: string lead_notes: type: string description: Anotações sobre o lead default: '' lead_isTicketOpen: type: boolean description: Indica se tem ticket aberto default: false lead_assignedAttendant_id: type: string description: ID do atendente responsável default: '' lead_kanbanOrder: type: integer format: int64 description: Ordem no kanban default: 0 lead_field01: type: string default: '' lead_field02: type: string default: '' lead_field03: type: string default: '' lead_field04: type: string default: '' lead_field05: type: string default: '' lead_field06: type: string default: '' lead_field07: type: string default: '' lead_field08: type: string default: '' lead_field09: type: string default: '' lead_field10: type: string default: '' lead_field11: type: string default: '' lead_field12: type: string default: '' lead_field13: type: string default: '' lead_field14: type: string default: '' lead_field15: type: string default: '' lead_field16: type: string default: '' lead_field17: type: string default: '' lead_field18: type: string default: '' lead_field19: type: string default: '' lead_field20: type: string default: '' chatbot_agentResetMemoryAt: type: integer format: int64 description: >- Início da memória da IA (ms): o agente só lê as mensagens da conversa a partir daqui. 0: sem corte (vale a janela do agente). Grave pelo `/chat/editLead`. default: 0 chatbot_lastTrigger_id: type: string description: ID do último gatilho executado default: '' chatbot_lastTriggerAt: type: integer format: int64 description: Timestamp do último gatilho default: 0 chatbot_disableUntil: type: integer format: int64 description: >- Automação (IA, gatilhos e fluxos) pausada nesta conversa até este horário, em milissegundos. `-1`: até alguém religar; `0`: ligada. default: 0 chatbot_summary: type: string description: >- Motivo da pausa feita pela automação: pedido de humano (IA ou fluxo; pausa até alguém religar) ou limite de respostas da IA (pausa de 1 hora). Vazio quando não há pausa ou depois que ela acaba. Religar (`chatbot_disableUntil: 0` no `/chat/editLead`) ou concluir (`POST /lead/resolve`) limpa. default: '' securitySchemes: token: name: token type: apiKey in: header ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.