# n8n Source: https://docs.wppfy.com/pt-BR/api-reference/n8n Automatize o WhatsApp no n8n com os nós oficiais da WppFy. O pacote [`n8n-nodes-wppfy`](https://www.npmjs.com/package/n8n-nodes-wppfy) adiciona dois nós ao n8n: Todas as rotas desta documentação como operações: enviar mensagens, gerenciar chats, grupos, canais, etiquetas, CRM, catálogo e mais. Inicia um workflow quando chegam mensagens e outros eventos do WhatsApp. O webhook é criado e removido automaticamente. ## Instalação 1. No n8n, acesse **Settings → Community Nodes**. 2. Clique em **Install**. 3. Digite `n8n-nodes-wppfy`, aceite o aviso e clique em **Install**. ```bash theme={null} cd ~/.n8n/nodes npm install n8n-nodes-wppfy # reinicie o n8n ``` No Docker, rode o comando dentro do container (ou no volume `~/.n8n/nodes`) e reinicie. ## Credencial Crie uma credencial **WppFy API**: | Campo | Valor | | - | - | | **Instance Token** | Token da sua instância, disponível no [painel da WppFy](https://wppfy.com/dashboard) | | **Base URL** | `https://api.wppfy.com` (padrão) | Ao salvar, o n8n testa a credencial com `GET /instance/status`. Cada credencial corresponde a uma instância: crie uma por número. ## Enviar mensagens (nó WppFy) 1. Adicione o nó **WppFy** ao workflow. 2. Escolha o **Resource** (por exemplo *Send Message*) e a **Operation** (por exemplo *Send text message*). 3. Preencha os campos obrigatórios. Os opcionais ficam em **Additional Fields → Add Field**. | Parâmetro | Exemplo | | - | - | | Resource | Send Message | | Operation | Send text message | | Number | `5511999999999` ou o ID de um grupo terminado em `@g.us` | | Text | `Olá {{ $json.nome }}!` | Campos com listas ou objetos (opções de menu, cards de carrossel, participantes de grupo) aceitam JSON. Você pode digitar o JSON ou usar uma expressão, como `{{ JSON.stringify($json.participantes) }}`. Os placeholders da WppFy, como `{{name}}` e `{{first_name}}`, funcionam em campos de texto comuns. Dentro de uma expressão do n8n, escreva `{{ "{{name}}" }}` para que o n8n não tente interpretá-los. ## Receber eventos (nó WppFy Trigger) 1. Adicione o nó **WppFy Trigger** e selecione a credencial. 2. Em **Events**, escolha os eventos que iniciam o workflow (padrão: *Messages*). 3. Em **Ignore Messages**, mantenha **Sent by API** se o workflow responder com o nó WppFy. Assim as próprias respostas não disparam o workflow de novo. 4. Ative o workflow. Ao **ativar**, o nó adiciona um webhook na instância apontando para o n8n. Ao **desativar**, esse webhook é removido. Webhooks que você já tem na instância não são alterados. Cada evento vira um item com o payload do evento (`EventType`, `message`, `chat`, `owner`...). O token da instância que vem no payload é removido por padrão; para mantê-lo, ative **Options → Include Instance Token**. O n8n precisa estar acessível pela internet para receber os eventos: n8n Cloud, ou self-hosted com `WEBHOOK_URL` público. Um n8n rodando só em `localhost` não recebe eventos. ## Agentes de IA O nó **WppFy** pode ser usado como ferramenta de um **AI Agent**. Adicione o WppFy como tool, escolha a operação que o agente pode usar (por exemplo *Send text message*) e deixe o modelo preencher os campos com `$fromAI()`. ## Operações disponíveis O nó segue os grupos da [Referência API](/pt-BR/api-reference/start-here): Instance, Proxy, Profile, Business, Calls, Send Message, Async Message, Message Actions and Search, Chats, Contacts, Blocklist, Labels, Groups and Communities, Newsletters and Channels, Quick Replies, CRM e Chatwoot Integration. A lista completa de operações está na [página do pacote no npm](https://www.npmjs.com/package/n8n-nodes-wppfy). # Comece Aqui Source: https://docs.wppfy.com/pt-BR/api-reference/start-here API potente para gestão de instâncias e automações no WhatsApp. Conecte-se, envie mensagens e gerencie eventos facilmente. **Base URL:** `https://api.wppfy.com` ## Documentação para IA Vai integrar usando um assistente de código? Escolha sua ferramenta, copie o prompt e cole no chat. Ele aponta a IA para o índice da documentação em [`llms.txt`](https://docs.wppfy.com/llms.txt) (versão completa em [`llms-full.txt`](https://docs.wppfy.com/llms-full.txt)). ```text Claude Code icon="https://www.google.com/s2/favicons?domain=claude.ai&sz=64" wrap theme={null} Vou integrar a API de WhatsApp da WppFy neste projeto. Antes de escrever código, leia a documentação em https://docs.wppfy.com/llms.txt e abra as páginas .md dos endpoints que forem necessários. Regras: - Base URL: https://api.wppfy.com - Autenticação: header `token` com o token da instância, lido de variável de ambiente (WPPFY_TOKEN), nunca fixo no código. - Siga exatamente os payloads e respostas da documentação; não invente campos nem endpoints. - Trate erros HTTP (401, 404, 429, 500) e o estado da instância (disconnected, connecting, connected). Tarefa: [descreva aqui o que você quer construir] ``` ```text Codex icon="https://www.google.com/s2/favicons?domain=openai.com&sz=64" wrap theme={null} Contexto: integração com a API de WhatsApp da WppFy. Documentação (índice para LLMs): https://docs.wppfy.com/llms.txt Documentação completa: https://docs.wppfy.com/llms-full.txt Leia a documentação antes de implementar. Use a Base URL https://api.wppfy.com e envie o header `token` com o token da instância vindo da variável de ambiente WPPFY_TOKEN. Use apenas endpoints e campos documentados, trate erros HTTP e escreva testes para as chamadas principais. Tarefa: [descreva aqui o que você quer construir] ``` ```text Cursor icon="https://www.google.com/s2/favicons?domain=cursor.com&sz=64" wrap theme={null} @https://docs.wppfy.com/llms.txt Use a documentação da WppFy acima como referência para integrar a API de WhatsApp neste projeto. - Base URL: https://api.wppfy.com - Header de autenticação: `token` (token da instância, via variável de ambiente WPPFY_TOKEN) - Consulte as páginas .md listadas no llms.txt para os payloads exatos de cada endpoint. - Não invente campos; trate erros e o estado de conexão da instância. Tarefa: [descreva aqui o que você quer construir] ``` ```text Replit icon="https://www.google.com/s2/favicons?domain=replit.com&sz=64" wrap theme={null} Crie uma integração com a API de WhatsApp da WppFy. Documentação: https://docs.wppfy.com/llms.txt (leia antes de começar). - Base URL: https://api.wppfy.com - Guarde o token da instância nos Secrets do Replit como WPPFY_TOKEN e envie no header `token`. - Para receber mensagens, exponha uma rota de webhook (POST) e registre os eventos recebidos. - Use somente endpoints e campos que estão na documentação. Tarefa: [descreva aqui o que você quer construir] ``` ```text Lovable icon="https://www.google.com/s2/favicons?domain=lovable.dev&sz=64" wrap theme={null} Quero adicionar envio e recebimento de mensagens de WhatsApp ao meu app usando a API da WppFy. Leia a documentação em https://docs.wppfy.com/llms.txt antes de implementar. - Base URL: https://api.wppfy.com - O token da instância é secreto: guarde como secret (WPPFY_TOKEN) e faça as chamadas pelo backend (Edge Function), nunca direto do navegador. - Envie o token no header `token`. - Siga os payloads exatamente como na documentação. Tarefa: [descreva aqui o que você quer construir] ``` ```text Bolt.new icon="https://www.google.com/s2/favicons?domain=bolt.new&sz=64" wrap theme={null} Integre a API de WhatsApp da WppFy neste app. Documentação para referência: https://docs.wppfy.com/llms.txt - Base URL: https://api.wppfy.com - Header `token` com o token da instância, lido de variável de ambiente (WPPFY_TOKEN) em um endpoint de servidor; não exponha o token no front-end. - Use apenas endpoints e campos documentados e trate os erros retornados pela API. Tarefa: [descreva aqui o que você quer construir] ``` ```text v0 icon="https://www.google.com/s2/favicons?domain=v0.app&sz=64" wrap theme={null} Construa a integração com a API de WhatsApp da WppFy. Documentação: https://docs.wppfy.com/llms.txt - Base URL: https://api.wppfy.com - Faça as chamadas pelo servidor, com o token da instância em variável de ambiente (WPPFY_TOKEN) enviado no header `token`. - Nunca exponha o token no client. - Siga os payloads da documentação sem inventar campos. Tarefa: [descreva aqui o que você quer construir] ``` ## Recomendação Importante **Use WhatsApp Business** Recomenda-se fortemente utilizar contas de **WhatsApp Business** para evitar desconexões, limitações de envio e instabilidade na conexão. ## Autenticação Para interagir com a API, você precisará configurar os *Headers* de suas solicitações. Escolha o tipo de acesso necessário: ```bash Token da Instância theme={null} # Header para rotas de envio e controle de sessão token: SEU_TOKEN_AQUI ``` ## Estados da Sessão Entenda o que significa cada estado de conexão para monitorar suas instâncias em tempo real. A instância está totalmente desconectada do servidor do WhatsApp. O sistema está tentando estabelecer o handshake com o WhatsApp. Conexão estável. A instância está pronta para enviar e receber dados. # Configurar Webhook Source: https://docs.wppfy.com/pt-BR/api-reference/webhooks Receba eventos em tempo real da sua instância via Webhook. # Webhook da Instância Gerencie a configuração para receber notificações de mensagens, conexões e outros eventos em tempo real no seu servidor. ## Ferramentas de Teste Antes de integrar, recomendamos testar o recebimento dos dados. Utilize uma dessas ferramentas para inspecionar o payload: **Recomendado.** Sem rate limit e interface super limpa. Boa alternativa. Confiável e com baixo rate limit. Evite se possível. Possui rate limits muito agressivos. *** ## Modo Simples (Recomendado) Esta é a forma mais fácil de configurar. O sistema gerencia automaticamente um único webhook por instância, criando ou atualizando conforme necessário. **Regras:** 1. Não inclua `action` nem `id` no payload. 2. Sempre use filtros para evitar loops infinitos. **Prevenção de Loops** Se você utiliza automações, **sempre** inclua `"excludeMessages": ["wasSentByApi"]`. Isso impede que mensagens enviadas pelo seu próprio robô disparem novos eventos, criando um loop infinito. ### Exemplo de Payload ```json theme={null} { "url": "https://meusite.com/webhook", "events": [ "messages", "connection" ], "excludeMessages": [ "wasSentByApi" ] } ``` *** ## Modo Avançado Utilize este modo apenas se precisar registrar **múltiplos webhooks** para a mesma instância (ex: um webhook para mensagens e outro para status de conexão). **Dica Pro:** Mesmo precisando de múltiplos endpoints, considere usar o recurso de **Parâmetros de URL** (veja no final da página) com o Modo Simples. É mais fácil de manter. ### Gerenciamento Manual Para controlar múltiplos webhooks, você deve enviar o campo `action`. ```json Criar (Add) theme={null} { "action": "add", "url": "https://api.site.com/webhook-1", "events": ["messages"] // O sistema gera um ID automaticamente } ``` ```json Atualizar (Update) theme={null} { "action": "update", "id": "ID_DO_WEBHOOK", // Obrigatório "url": "https://api.site.com/nova-url", "events": ["messages", "call"] } ``` ```json Deletar (Delete) theme={null} { "action": "delete", "id": "ID_DO_WEBHOOK" // Apenas o ID é necessário } ``` *** ## Eventos Disponíveis Selecione quais tipos de notificação você deseja receber no array `events`. | Evento | Descrição | | :- | :- | | `messages` | Novas mensagens recebidas. | | `messages_update` | Atualização de status (entregue, lido) ou edição. | | `history` | Recebimento do histórico de mensagens ao conectar. | | `chats` | Eventos relacionados à lista de conversas. | | `chat_labels` | Alterações em etiquetas de conversas. | | Evento | Descrição | | :- | :- | | `connection` | Alterações no estado (QR Code, Conectado, Desconectado). | | `presence` | Alterações no status de presença (online, digitando). | | `contacts` | Atualizações na agenda de contatos. | | `groups` | Modificações em grupos (título, participantes). | | `blocks` | Bloqueios e desbloqueios de contatos. | | `call` | Eventos de chamadas de voz/vídeo. | | Evento | Descrição | | :- | :- | | `leads` | Atualizações de leads. | | `labels` | Gerenciamento de etiquetas. | | `sender` | Atualizações de campanhas (início/término). | ## Filtros de Exclusão (`excludeMessages`) Use o campo `excludeMessages` para ignorar mensagens específicas e economizar processamento. | Filtro | Descrição | | :- | :- | | `wasSentByApi` | **Importante:** Ignora mensagens enviadas pela própria API. | | `wasNotSentByApi` | Ignora mensagens que NÃO foram enviadas pela API. | | `fromMeYes` | Ignora mensagens enviadas pelo próprio usuário (celular). | | `fromMeNo` | Ignora mensagens recebidas de outras pessoas. | | `isGroupYes` | Ignora mensagens vindas de grupos. | | `isGroupNo` | Ignora mensagens de conversas privadas (PV). | *** ## Parâmetros de URL (Rotas Dinâmicas) Você pode fazer com que a API adicione informações diretamente na URL do seu webhook, facilitando o roteamento no seu backend (ex: usar Node.js/Express ou Laravel Routes). ### Opções Disponíveis Adiciona o **evento** na URL. `.../webhook/{evento}` Adiciona o **tipo da mensagem** na URL. `.../webhook/{tipo}` ### Exemplos de Resultados Suponha que sua URL base seja `https://api.example.com/webhook`: 1. **Apenas Eventos (`addUrlEvents: true`):** * `https://api.example.com/webhook/message` * `https://api.example.com/webhook/connection` 2. **Apenas Tipos (`addUrlTypesMessages: true`):** * `https://api.example.com/webhook/conversation` (texto) * `https://api.example.com/webhook/image` (mídia) 3. **Ambos Ativos (Combinação):** A ordem é sempre: `{URL_BASE}/{EVENTO}/{TIPO_MENSAGEM}` * `https://api.example.com/webhook/message/conversation` * `https://api.example.com/webhook/message/audio` Certifique-se de que seu backend esteja configurado para aceitar **parâmetros dinâmicos** (wildcards) na rota para processar essas URLs corretamente. # Limpar fila async de envio direto Source: https://docs.wppfy.com/pt-br/api-reference/async-message/clear-direct-send-async-queue /openapi-pt-BR.json delete /message/async Cancela toda a fila de envio `async=true` da instância e marca as mensagens pendentes como `Canceled`. Este endpoint atua apenas nos envios diretos com `async=true`. Ele **não** afeta: - mensagens já enviadas com sucesso Use quando houver uma fila acumulada ou quando for necessário cancelar todos os envios assíncronos ainda não concluídos. Depois da limpeza, a instância volta a aceitar novos envios com `async=true`. # Configurar delay entre mensagens async Source: https://docs.wppfy.com/pt-br/api-reference/async-message/configure-delay-between-async-messages /openapi-pt-BR.json post /instance/updateDelaySettings Configura o intervalo de tempo entre mensagens diretas enviadas com `async=true`. ### Detalhes - Configuração aplicada apenas à fila interna de mensagens async - Afeta mensagens enviadas pelos endpoints de envio com `async=true` - Delay mínimo (msg_delay_min): 0 ou mais segundos (0 = sem delay) - Delay máximo (msg_delay_max): se menor que min, será ajustado para o mesmo valor de min - Sistema ajusta automaticamente valores negativos para 0 ### Exemplo ```json { "msg_delay_min": 0, "msg_delay_max": 2 } ``` # Consultar fila async de envio direto Source: https://docs.wppfy.com/pt-br/api-reference/async-message/get-the-direct-send-async-queue /openapi-pt-BR.json get /message/async Retorna um resumo simples da fila de envio `async=true` da instância atual autenticada. Este endpoint cobre apenas mensagens diretas enviadas com `async=true`. A resposta padrão foi pensada para clientes: - `status`: visão resumida da fila (`idle`, `queued`, `processing`, `waiting_connection`, `waiting_warmup`, `waiting_history`, `resetting`) - `pending`: quantidade total estimada de mensagens pendentes - `processingNow`: indica se uma mensagem está sendo processada neste momento - `acceptingNewMessages`: indica se a fila aceita novos envios async - `sessionReady`: indica se a sessão WhatsApp está pronta para envio - `resetting`: indica se a fila está pausada por reset/clear # Bloqueia ou desbloqueia contato do WhatsApp Source: https://docs.wppfy.com/pt-br/api-reference/blocklist/blocks-or-unblocks-a-whatsapp-contact /openapi-pt-BR.json post /chat/block Bloqueia ou desbloqueia um contato do WhatsApp. Contatos bloqueados não podem enviar mensagens para a instância e a instância não pode enviar mensagens para eles. # Lista contatos bloqueados Source: https://docs.wppfy.com/pt-br/api-reference/blocklist/list-blocked-contacts /openapi-pt-BR.json get /chat/blocklist Retorna a lista completa de contatos que foram bloqueados pela instância. Esta lista é atualizada em tempo real conforme contatos são bloqueados/desbloqueados. # Conclui conversas (aguardando você) Source: https://docs.wppfy.com/pt-br/api-reference/crm/completes-conversations-awaiting-you /openapi-pt-BR.json post /lead/resolve Tira conversas de "aguardando você" sem responder (o contato mandou "obrigado", por exemplo): `lead_awaitingReply` vira `false` e o pedido de humano (`chatbot_summary`) sai, sem religar a IA. A próxima mensagem do contato volta a ligar a espera. Mande em `lastMessageTimestamp` o horário da última mensagem que a tela mostrava: o que chegou depois continua esperando. Para concluir todas, envie as conversas da lista "aguardando você" (`/chat/find` com `lead_awaitingReply: true`). Conversa que não existe é ignorada. # Cria, edita ou apaga uma tag de lead Source: https://docs.wppfy.com/pt-br/api-reference/crm/creates-edits-or-deletes-a-lead-tag /openapi-pt-BR.json post /lead/tags/edit Cria uma tag quando `id` não é informado ou edita uma tag da instância autenticada quando `id` está presente. Use `kanban=true` para transformar a tag em uma coluna do quadro e `kanban=false` para retirá-la do Kanban sem apagar a tag. A alteração vale somente para a instância autenticada. Use `delete=true` junto de `id` para apagar definitivamente a tag. Ao apagar, a tag também é removida dos chats que a utilizam. # Edita informações de lead Source: https://docs.wppfy.com/pt-br/api-reference/crm/edits-lead-information /openapi-pt-BR.json post /chat/editLead Atualiza as informações de lead associadas a um chat. Permite modificar status do ticket, atribuição de atendente, posição no kanban, tags e outros campos customizados. As alterações ficam disponíveis imediatamente nas consultas e nos eventos webhook/SSE. para manter a aplicação sincronizada. # Lista tags de lead Source: https://docs.wppfy.com/pt-br/api-reference/crm/list-lead-tags /openapi-pt-BR.json get /lead/tags Retorna as tags pertencentes à instância autenticada. Registros com `kanban=true` representam as colunas ativas do Kanban. A resposta é ordenada com as colunas ativas primeiro, seguidas por `kanbanOrder` e nome. O endpoint usa somente dados locais e funciona mesmo quando a sessão do WhatsApp está desconectada. # Nomear campos personalizados de leads Source: https://docs.wppfy.com/pt-br/api-reference/crm/name-lead-custom-fields /openapi-pt-BR.json post /instance/updateFieldsMap Configura os rótulos dos 20 campos personalizados de leads de uma instância. Esta operação não altera os valores armazenados nos chats e não cria aliases para placeholders. Os campos disponíveis são `lead_field01` a `lead_field20`. Mesmo depois de definir um rótulo, mensagens devem usar o nome original do slot. Por exemplo, se `lead_field01` for rotulado como `empresa`, o placeholder continua sendo `{{lead_field01}}`; `{{empresa}}` não será substituído. Use os rótulos para informar à sua interface o significado de cada slot. Os valores de cada lead são gravados pelas operações de CRM no respectivo `lead_fieldXX`. Exemplo de requisição: ```json { "lead_field01": "nome", "lead_field02": "email", "lead_field03": "telefone", "lead_field04": "cidade", "lead_field05": "estado", "lead_field06": "idade", "lead_field07": "interesses", "lead_field08": "origem", "lead_field09": "status", "lead_field10": "valor", "lead_field11": "observacoes", "lead_field12": "ultima_interacao", "lead_field13": "proximo_contato", "lead_field14": "vendedor", "lead_field15": "produto_interesse", "lead_field16": "fonte_captacao", "lead_field17": "score", "lead_field18": "tags", "lead_field19": "historico", "lead_field20": "custom" } ``` Exemplo de resposta: ```json { "success": true, "message": "Custom fields updated successfully", "instance": { "id": "r183e2ef9597845", "name": "minha-instancia", "fieldsMap": { "lead_field01": "nome", "lead_field02": "email", "lead_field03": "telefone", "lead_field04": "cidade", "lead_field05": "estado", "lead_field06": "idade", "lead_field07": "interesses", "lead_field08": "origem", "lead_field09": "status", "lead_field10": "valor", "lead_field11": "observacoes", "lead_field12": "ultima_interacao", "lead_field13": "proximo_contato", "lead_field14": "vendedor", "lead_field15": "produto_interesse", "lead_field16": "fonte_captacao", "lead_field17": "score", "lead_field18": "tags", "lead_field19": "historico", "lead_field20": "custom" } } } ``` Erros comuns: - 400: Campos inválidos ou payload mal formatado - 401: Token inválido ou expirado - 404: Instância não encontrada - 500: Erro ao atualizar campos no banco de dados Envie o mapa completo. Campos omitidos são recebidos como vazios e podem substituir rótulos configurados anteriormente. # Configurar aprovação para entrada no grupo Source: https://docs.wppfy.com/pt-br/api-reference/groups-and-communities/configure-approval-for-joining-the-group /openapi-pt-BR.json post /group/updateJoinApproval Define se novos participantes precisam ser aprovados antes de entrar no grupo. No objeto retornado em `group` e também em `/group/info`, esse estado aparece no campo `IsJoinApprovalRequired`. Quando ativado (`IsJoinApprovalRequired=true`): - Novas entradas passam por aprovação de administrador - Solicitações pendentes podem ser listadas em `/group/info` Quando desativado (`IsJoinApprovalRequired=false`): - Entradas por link/convite não exigem aprovação adicional Requer que o usuário seja administrador do grupo. # Configurar mensagens temporárias em grupo Source: https://docs.wppfy.com/pt-br/api-reference/groups-and-communities/configure-disappearing-messages-in-a-group /openapi-pt-BR.json post /group/ephemeral Define o temporizador de mensagens temporárias (disappearing messages) de um grupo. Valores aceitos para a duração: - `0` ou `off` para desativar - `1d` - `7d` - `90d` Observações: - este endpoint é apenas para grupos - requer privilégios de administrador do grupo - se o identificador informado não for de grupo, a API retorna erro orientando usar `/chat/ephemeral` - após sucesso, a resposta devolve o chat e os dados atualizados do grupo # Configurar permissão de edição do grupo Source: https://docs.wppfy.com/pt-br/api-reference/groups-and-communities/configure-group-editing-permissions /openapi-pt-BR.json post /group/updateLocked Define se apenas administradores podem editar as informações do grupo. Quando bloqueado (locked=true), apenas administradores podem alterar nome, descrição, imagem e outras configurações do grupo. Quando desbloqueado (locked=false), qualquer participante pode editar as informações. Importante: - Requer que o usuário seja administrador do grupo - Afeta edições de nome, descrição, imagem e outras informações do grupo - Não controla permissões de adição de membros # Configurar permissões de envio de mensagens no grupo Source: https://docs.wppfy.com/pt-br/api-reference/groups-and-communities/configure-group-messaging-permissions /openapi-pt-BR.json post /group/updateAnnounce Define as permissões de envio de mensagens no grupo, permitindo restringir o envio apenas para administradores. Quando ativado (announce=true): - Apenas administradores podem enviar mensagens - Outros participantes podem apenas ler - Útil para anúncios importantes ou controle de spam Quando desativado (announce=false): - Todos os participantes podem enviar mensagens - Configuração padrão para grupos normais Requer que o usuário seja administrador do grupo para fazer alterações. # Configurar quem pode adicionar novos membros ao grupo Source: https://docs.wppfy.com/pt-br/api-reference/groups-and-communities/configure-who-can-add-new-members-to-the-group /openapi-pt-BR.json post /group/updateMemberAddMode Define quem tem permissão para adicionar novos participantes diretamente ao grupo. No objeto retornado em `group` e também em `/group/info`, esse estado aparece no campo `MemberAddMode`. Valores aceitos em `MemberAddMode`: - `admin_add`: apenas administradores podem adicionar membros - `all_member_add`: qualquer participante pode adicionar membros Requer que o usuário seja administrador do grupo. # Criar uma comunidade Source: https://docs.wppfy.com/pt-br/api-reference/groups-and-communities/create-a-community /openapi-pt-BR.json post /community/create Cria uma nova comunidade no WhatsApp. Uma comunidade é uma estrutura que permite agrupar múltiplos grupos relacionados sob uma única administração. A comunidade criada inicialmente terá apenas o grupo principal (announcements), e grupos adicionais podem ser vinculados posteriormente usando o endpoint `/community/updategroups`. **Observações importantes:** - O número que cria a comunidade torna-se automaticamente o administrador - A comunidade terá um grupo principal de anúncios criado automaticamente # Criar um novo grupo Source: https://docs.wppfy.com/pt-br/api-reference/groups-and-communities/create-a-new-group /openapi-pt-BR.json post /group/create Cria um grupo com participantes iniciais opcionais. O WhatsApp inclui o criador automaticamente. Envie `participants: []`, omita o campo ou use `null` para criar um grupo somente com o criador. Informar apenas o próprio PN/LID tem o mesmo efeito; não é necessário adicionar o criador manualmente. Para adicionar outras pessoas, informe números com DDI (apenas dígitos) ou JIDs PN completos, como `5511999999999@s.whatsapp.net`. JIDs LID conhecidos pela instância também são aceitos. Participantes são verificados e duplicatas/aliases do criador são removidos. Uma lista com convidados inválidos e nenhum convidado válido continua retornando 400; ela não é convertida silenciosamente em grupo vazio. A resposta contém `group` e `failed`. Quem a privacidade impediu de entrar fica em `failed`, sem o código do convite individual: para convidar, chame `POST /group/updateParticipants` com `action: add` (veja [Convidar pessoas](/docs/groups#convidar-pessoas)). Depois da criação, o administrador pode obter o convite em `GET /group/invitelink/{groupJID}`, usando `group.JID`. # Gerar link de convite para um grupo Source: https://docs.wppfy.com/pt-br/api-reference/groups-and-communities/generate-invite-link-for-a-group /openapi-pt-BR.json get /group/invitelink/{groupJID} Retorna o link de convite para o grupo especificado. Esta operação requer que a conta conectada seja administradora do grupo. # Consultar detalhes e membros de um grupo Source: https://docs.wppfy.com/pt-br/api-reference/groups-and-communities/get-group-details-and-members /openapi-pt-BR.json post /group/info Use esta operação depois de selecionar um grupo na listagem. Informe apenas `groupjid` para receber dados, participantes conhecidos e permissões daquele grupo. Fotos e informações da comunidade relacionada são incluídas quando disponíveis. ### Opções avançadas - getInviteLink e getRequestsParticipants solicitam dados adicionais, somente para administrador com permissão confirmada. Os campos podem estar ausentes sem essa permissão. - force solicita atualização remota; deixe false no fluxo normal. - O uso normal precisa apenas de `groupjid`; adicione opções avançadas somente quando necessárias. # Obter informações de um grupo pelo código de convite Source: https://docs.wppfy.com/pt-br/api-reference/groups-and-communities/get-group-information-by-invite-code /openapi-pt-BR.json post /group/inviteInfo Mostra os dados de um grupo a partir do link de convite ou do código, sem entrar nele. Use para conferir nome, participantes e restrições antes de chamar `POST /group/join`. # Entrar em um grupo usando código de convite Source: https://docs.wppfy.com/pt-br/api-reference/groups-and-communities/join-a-group-using-an-invite-code /openapi-pt-BR.json post /group/join Entra num grupo pelo link de convite do grupo (`https://chat.whatsapp.com/`) ou só pelo código. Aceita apenas o link de convite. O código de um convite individual (o cartão "Entrar no grupo" recebido numa conversa) não funciona aqui, e a API ainda não tem rota para aceitar esse convite. A resposta traz o JID do grupo em `group`; consulte os detalhes depois em `POST /group/info`. # Sair de um grupo Source: https://docs.wppfy.com/pt-br/api-reference/groups-and-communities/leave-a-group /openapi-pt-BR.json post /group/leave Remove o usuário atual de um grupo específico do WhatsApp. Requisitos: - O usuário deve estar conectado a uma instância válida - O usuário deve ser um membro do grupo Comportamentos: - Se o usuário for o último administrador, o grupo será dissolvido - Se o usuário for um membro comum, será removido do grupo # Listar todos os grupos (legado) Source: https://docs.wppfy.com/pt-br/api-reference/groups-and-communities/list-all-groups-legacy /openapi-pt-BR.json get /group/list Mantido para integrações existentes. Retorna a coleção de grupos sem paginação e pode produzir uma resposta grande. Para novas integrações, prefira POST /group/list. ### Opções avançadas `noParticipants=true` retorna a lista sem membros, como no POST. `force` pode reutilizar uma atualização recente. Para consultar membros, use POST /group/info no grupo escolhido. # Listar grupos em páginas (recomendado) Source: https://docs.wppfy.com/pt-br/api-reference/groups-and-communities/list-groups-in-pages-recommended /openapi-pt-BR.json post /group/list Use esta operação para buscar grupos e escolher qual abrir. Prefira uma página de resumos sem a lista de membros; consulte POST /group/info quando precisar dos detalhes de um grupo. ### Uso recomendado Envie search, limit e offset, com noParticipants=true. O padrão de página é 50 e o máximo é 1000. A busca considera nome, JID, descrição do grupo e nome da comunidade à qual ele pertence. A resposta contém groups e pagination. ### Opções avançadas e compatibilidade - O default HTTP de noParticipants continua false para preservar integrações existentes. O exemplo recomendado usa true explicitamente. - Para participantes e perfis completos, consulte somente o grupo selecionado em POST /group/info. - force solicita atualização do WhatsApp. Normalmente basta deixar a API atualizar quando necessário; não use force em polling contínuo. Uma atualização remota da lista ainda pode receber participantes do WhatsApp; noParticipants=true evita carregá-los na leitura da página e enviá-los na resposta. # Gerenciar participantes do grupo Source: https://docs.wppfy.com/pt-br/api-reference/groups-and-communities/manage-group-participants /openapi-pt-BR.json post /group/updateParticipants Gerencia participantes do grupo através de diferentes ações: - Adicionar ou remover participantes - Promover ou rebaixar administradores - Aprovar ou rejeitar solicitações pendentes Requer que o usuário seja administrador do grupo para executar as ações. Com `action: add`, quem a privacidade bloqueia volta em `groupUpdated` com `Error: 403` e `AddRequest`. Use esse código para enviar um convite individual (veja [Convidar pessoas](/docs/groups#convidar-pessoas)). # Gerenciar grupos em uma comunidade Source: https://docs.wppfy.com/pt-br/api-reference/groups-and-communities/manage-groups-in-a-community /openapi-pt-BR.json post /community/editgroups Adiciona ou remove grupos de uma comunidade do WhatsApp. Apenas administradores da comunidade podem executar estas operações. ## Funcionalidades - Adicionar múltiplos grupos simultaneamente a uma comunidade - Remover grupos de uma comunidade existente - Suporta operações em lote ## Limitações - Os grupos devem existir previamente - A comunidade deve existir e o usuário deve ser administrador - Grupos já vinculados não podem ser adicionados novamente - Grupos não vinculados não podem ser removidos ## Ações Disponíveis - `add`: Adiciona os grupos especificados à comunidade - `remove`: Remove os grupos especificados da comunidade # Resetar código de convite do grupo Source: https://docs.wppfy.com/pt-br/api-reference/groups-and-communities/reset-group-invite-code /openapi-pt-BR.json post /group/resetInviteCode Gera um novo código de convite para o grupo, invalidando o código de convite anterior. Somente administradores do grupo podem realizar esta ação. Principais características: - Invalida o link de convite antigo - Cria um novo link único - Retorna as informações atualizadas do grupo # Atualizar descrição do grupo Source: https://docs.wppfy.com/pt-br/api-reference/groups-and-communities/update-group-description /openapi-pt-BR.json post /group/updateDescription Altera a descrição (tópico) do grupo WhatsApp especificado. Requer que o usuário seja administrador do grupo. A descrição aparece na tela de informações do grupo e pode ser visualizada por todos os participantes. # Atualizar imagem do grupo Source: https://docs.wppfy.com/pt-br/api-reference/groups-and-communities/update-group-image /openapi-pt-BR.json post /group/updateImage Altera a imagem do grupo especificado. A imagem pode ser enviada como URL ou como string base64. Requisitos da imagem: - Formato: JPEG - Resolução máxima: 640x640 pixels - Imagens maiores ou diferente de JPEG não são aceitas pelo WhatsApp Para remover a imagem atual, envie "remove" ou "delete" no campo image. # Atualizar nome do grupo Source: https://docs.wppfy.com/pt-br/api-reference/groups-and-communities/update-group-name /openapi-pt-BR.json post /group/updateName Altera o nome de um grupo do WhatsApp. Apenas administradores do grupo podem realizar esta operação. O nome do grupo deve seguir as diretrizes do WhatsApp e ter entre 1 e 25 caracteres. # Consultar o processamento do histórico inicial Source: https://docs.wppfy.com/pt-br/api-reference/instance/check-the-initial-history-processing /openapi-pt-BR.json get /instance/history-sync/status Retorna o diagnóstico em memória da sincronização de histórico iniciada no pareamento mais recente desta instância. Não inicia uma nova sincronização. O `request_id` é o mesmo devolvido por `POST /instance/connect` para essa tentativa e pelos lotes `history` do pareamento. O diagnóstico só existe após o pareamento: antes disso, pode retornar `diagnosis: [no_trace]`. Esse endpoint não acompanha os pedidos manuais de `POST /message/history-sync`; use o `request_id` desses pedidos nos eventos webhook/SSE. `deliveryStatus` pode ser `pending`, `delivered`, `partial`, `failed`, `no_webhook` ou `no_batches`. O progresso informado pelo WhatsApp chegar a 100 não significa, sozinho, que todos os lotes já foram entregues. O rastreamento é isolado por instância, limitado aos eventos recentes e reiniciado junto com o processo. URLs de webhook podem aparecer no diagnóstico; trate a resposta como informação operacional sensível. # Conectar instância ao WhatsApp Source: https://docs.wppfy.com/pt-br/api-reference/instance/connect-instance-to-whatsapp /openapi-pt-BR.json post /instance/connect Inicia a conexão da instância com o WhatsApp. - Sem `phone`, retorna um QR Code para leitura no celular. - Com `phone`, retorna um código de pareamento para esse número. A instância permanece em `connecting` até o pareamento ser confirmado ou o prazo expirar. Acompanhe a evolução em `GET /instance/status`; não repita a chamada enquanto o processo estiver em andamento. Após a conexão, o histórico disponível começa a chegar pelo evento `history` e pode ser consultado em `POST /message/find` e `POST /chat/find`. A resposta pode incluir `request_id` no topo, antes mesmo da leitura do QR code ou do código de pareamento. Guarde esse id para correlacionar a tentativa com os lotes `history` do pareamento, inclusive o `status` de conclusão, e com `GET /instance/history-sync/status`. Ele permanece igual durante a mesma tentativa e muda a cada novo pareamento. Pode estar ausente quando não há pareamento nem rastreamento disponível. Em um pareamento novo, `history_days` escolhe quantos dias de histórico o celular envia. Sem o campo, com valor fora de 0–365 ou de 1 a 90 dias, o pedido é o histórico normal (90 dias, quando não há um valor válido). De 91 a 365 dias, ou com `0` (o máximo, 365 dias), o pedido é o histórico completo, maior e mais demorado. Uma instância já pareada reconecta sem pedir histórico. Para escolher uma região de conexão, consulte primeiro `GET /proxy-managed/countries` e `GET /proxy-managed/cities` e reutilize os valores retornados nos campos `proxy_managed_*`. # Desconectar instância Source: https://docs.wppfy.com/pt-br/api-reference/instance/disconnect-instance /openapi-pt-BR.json post /instance/disconnect Desconecta a conta do WhatsApp atualmente conectada, encerrando a sessão atual. Esta operação: - Encerra a conexão ativa - Requer novo QR code para reconectar Diferenças entre desconectar e hibernar: - Desconectar: Encerra completamente a sessão, exigindo novo login - Hibernar: Mantém a sessão ativa, apenas pausa a conexão Use este endpoint para: 1. Encerrar completamente uma sessão 2. Forçar uma nova autenticação 3. Limpar credenciais da sessão atual 4. Reiniciar o processo de conexão Estados possíveis após desconectar: - `disconnected`: Desconectado do WhatsApp - `connecting`: Em processo de reconexão (após usar /instance/connect) # Consultar limites atuais de novas conversas no WhatsApp Source: https://docs.wppfy.com/pt-br/api-reference/instance/get-current-limits-for-new-whatsapp-conversations /openapi-pt-BR.json get /instance/wa_messages_limits Consulta o estado atual de limitação do WhatsApp para a conta atualmente conectada. Este endpoint é útil para: - diagnosticar erros de envio com `provider_code: 463` - verificar se o WhatsApp indica que a conta atualmente conectada pode iniciar novas conversas - exibir informações de suporte antes de campanhas ou envios de alto volume A resposta consolida duas fontes internas do WhatsApp: - `new_chat_message_capping`: limite de mensagens para iniciar novas conversas - `reachout_timelock`: restrição temporária para iniciar novas conversas Observações: - este endpoint depende de sessão ativa e conectada - se o WhatsApp não retornar os dados esperados, a resposta pode marcar os blocos como indisponíveis via `available: false` e `lookup_error` - `message` descreve o estado atual da conta atualmente conectada - `provider_message` detalha o motivo reportado pelo WhatsApp quando houver restrição ativa # Verificar status da instância Source: https://docs.wppfy.com/pt-br/api-reference/instance/get-instance-status /openapi-pt-BR.json get /instance/status Retorna o status atual de uma instância, incluindo: - Estado da conexão - QR code atualizado (se em processo de conexão) - Código de pareamento (se disponível) - Informações da última desconexão - Detalhes completos da instância Este endpoint é particularmente útil para: 1. Monitorar o progresso da conexão 2. Obter QR codes atualizados durante o processo de conexão 3. Verificar o estado atual da instância 4. Identificar problemas de conexão Estados possíveis: - `disconnected`: Desconectado do WhatsApp - `connecting`: Em processo de conexão (aguardando QR code ou código de pareamento) - `connected`: Conectado e autenticado com sucesso - `hibernated`: Sessão pausada, com credenciais preservadas para reconexão # Reiniciar a conexão da instância Source: https://docs.wppfy.com/pt-br/api-reference/instance/restart-the-instance-connection /openapi-pt-BR.json post /instance/reset Solicita uma retomada controlada da conexão sem apagar a instância nem o pareamento existente. Use quando a sessão estiver presa ou os envios não estiverem progredindo. Comportamentos possíveis: - inicia um novo reset quando a instância está apta - informa que um reset já está em andamento - informa que existe cooldown ativo entre resets - retorna erro quando a sessão não pode ser recuperada ou quando a política de reconexão bloqueia a operação A resposta informa: - `instanceId`: ID da instância autenticada - `resetting`: se há reset em andamento no momento - `queuedRecoveryAttempted`: se mensagens pendentes também entraram na tentativa de recuperação # Atualizar status de presença da instância Source: https://docs.wppfy.com/pt-br/api-reference/instance/update-instance-presence-status /openapi-pt-BR.json post /instance/presence Atualiza o status de presença global da conta do WhatsApp atualmente conectada. Este endpoint permite: 1. Definir se a conta aparece como disponível ("online") ou indisponível 2. Controlar o status de presença para todos os contatos 3. Salvar o estado atual da presença para a conta conectada Tipos de presença suportados: - available: Marca a conta como disponível/online - unavailable: Marca a conta como indisponível/offline **Atenção**: - O status de presença pode ser temporariamente alterado para "available" (online) em algumas situações internas da API, e com isso o visto por último também pode ser atualizado. - Caso isso for um problema, considere alterar suas configurações de privacidade no WhatsApp para não mostrar o visto por último e/ou quem pode ver seu status "online". **⚠️ Importante - Limitação do Presence "unavailable"**: - **Quando a API é o único dispositivo ativo**: Confirmações de entrega/leitura (ticks cinzas/azuis) não são enviadas nem recebidas - **Impacto**: Eventos `message_update` com status de entrega podem não ser recebidos - **Solução**: Se precisar das confirmações, mantenha WhatsApp Web ou aplicativo móvel ativo ou use presence "available" Exemplo de requisição: ```json { "presence": "available" } ``` Exemplo de resposta: ```json { "response": "Presence updated successfully" } ``` Erros comuns: - 401: Token inválido ou expirado - 400: Valor de presença inválido - 500: Erro ao atualizar presença # Criar, editar ou deletar etiqueta Source: https://docs.wppfy.com/pt-br/api-reference/labels/create-edit-or-delete-label /openapi-pt-BR.json post /label/edit Cria, edita ou deleta uma etiqueta da instância. Regras de uso: - Para editar uma etiqueta existente, envie o `labelid` real da etiqueta. - Para criar uma nova etiqueta, envie `labelid: "new"` com `delete: false`. A API gera o próximo `labelid` numérico disponível para a instância. - Para deletar uma etiqueta existente, envie o `labelid` real com `delete: true`. Observações: - A resposta de sucesso retorna `"Label created"` para criação e `"Label edited"` para edição. - Para descobrir o `labelid` final criado, consulte `GET /labels` após a operação ou consuma o webhook/evento de labels da instância. # Buscar todas as etiquetas Source: https://docs.wppfy.com/pt-br/api-reference/labels/fetch-all-labels /openapi-pt-BR.json get /labels Lista as etiquetas disponíveis para organizar conversas e filtros da instância. Use os IDs retornados em `POST /chat/labels`. # Gerencia labels de um chat Source: https://docs.wppfy.com/pt-br/api-reference/labels/manages-a-chat-s-labels /openapi-pt-BR.json post /chat/labels Atualiza as labels associadas a um chat específico. Este endpoint oferece três modos de operação: 1. **Definir todas as labels** (labelids): Define o conjunto completo de labels para o chat, substituindo labels existentes 2. **Adicionar uma label** (add_labelid): Adiciona uma única label ao chat sem afetar as existentes 3. **Remover uma label** (remove_labelid): Remove uma única label do chat sem afetar as outras **Importante**: Use apenas um dos três parâmetros por requisição. Labels inexistentes serão rejeitadas. As labels devem ser fornecidas no formato id ou labelid encontradas na função get labels. # Iniciar recarga de etiquetas do WhatsApp Source: https://docs.wppfy.com/pt-br/api-reference/labels/start-whatsapp-label-refresh /openapi-pt-BR.json post /labels/refresh Inicia uma nova leitura das etiquetas no WhatsApp sem bloquear a requisição. A resposta confirma apenas que a recarga foi iniciada ou que já existe uma recarga em andamento. Para obter a lista atualizada, consulte `GET /labels` depois. A recarga também atualiza as associações entre etiquetas e chats. Quando houver mudança, o webhook `chat_labels` pode informar os dados atualizados. A resposta traz um `request_id`, repetido nos webhooks `history` (`labels` e `chat_labels`) dessa recarga. Se já houver uma recarga em andamento, o `request_id` é o dela. Uso recomendado: - tente primeiro com `force=false` - se isso não trouxer as etiquetas corretamente, tente `force=true` - use `force=true` apenas como tentativa de correção, porque ele faz uma recarga mais pesada # Apagar Mensagem Para Todos Source: https://docs.wppfy.com/pt-br/api-reference/message-actions-and-search/delete-message-for-everyone /openapi-pt-BR.json post /message/delete Apaga uma mensagem para todos os participantes da conversa. ### Funcionalidades: - Apaga mensagens em conversas individuais ou grupos - Funciona com mensagens enviadas pelo usuário ou recebidas - Atualiza o status no histórico da instância - Envia webhook de atualização **Notas Técnicas**: 1. O ID da mensagem pode ser fornecido em dois formatos: - ID completo (contém ":"): usado diretamente - ID curto: associado automaticamente à instância autenticada 2. Gera evento webhook do tipo "messages_update" 3. Atualiza o status da mensagem para "Deleted" 4. Para newsletters/canais, use `POST /newsletter/messages/delete` # Baixar arquivo de uma mensagem Source: https://docs.wppfy.com/pt-br/api-reference/message-actions-and-search/download-file-from-a-message /openapi-pt-BR.json post /message/download Baixa o arquivo associado a uma mensagem de mídia (imagem, vídeo, áudio, documento ou sticker). ## Parâmetros - **id** (string, obrigatório): ID da mensagem - **return_base64** (boolean, default: false): Inclui o arquivo em base64. Evite esta opção porque aumenta o uso de memória, processamento e o tamanho da resposta. Versões futuras poderão limitar base64 para arquivos maiores que 5 MB. - **generate_mp3** (boolean, default: true): Para áudios, define formato de retorno - `true`: Retorna MP3 - `false`: Retorna OGG - **return_link** (boolean, mantido para compatibilidade): A resposta inclui a URL pública do arquivo - **transcribe** (boolean, default: false): Transcreve áudios para texto - **openai_apikey** (string, opcional): Chave OpenAI para transcrição - Se não informada, usa a chave salva na instância - Se informada, atualiza e salva na instância para próximas chamadas - **download_quoted** (boolean, default: false): Baixa mídia da mensagem citada - Útil para baixar conteúdo original de status do WhatsApp - Quando uma mensagem é resposta a um status, permite baixar a mídia do status original - **Contextualização**: Ao baixar a mídia citada, você identifica o contexto da conversa - Exemplo: Se alguém responde a uma promoção, baixando a mídia você saberá que a pergunta é sobre aquela promoção específica ## Exemplos ### Baixar áudio como MP3: ```json { "id": "7EB0F01D7244B421048F0706368376E0", "generate_mp3": true } ``` ### Transcrever áudio: ```json { "id": "7EB0F01D7244B421048F0706368376E0", "transcribe": true } ``` ### Incluir o conteúdo em base64: ```json { "id": "7EB0F01D7244B421048F0706368376E0", "return_base64": true } ``` ### Baixar mídia de status (mensagem citada): ```json { "id": "7EB0F01D7244B421048F0706368376E0", "download_quoted": true } ``` *Útil quando o cliente responde a uma promoção/status - você baixa a mídia original para entender sobre qual produto/oferta ele está perguntando.* ## Resposta ```json { "fileURL": "https://api.exemplo.com/files/arquivo.mp3", "mimetype": "audio/mpeg", "base64Data": "UklGRkj...", "transcription": "Texto transcrito" } ``` **Nota**: - Por padrão, áudios são retornados como MP3 e todos os downloads incluem uma URL pública em `fileURL`. - Evite `return_base64: true`: a conversão aumenta o uso de memória e processamento no servidor e produz uma resposta maior. Prefira baixar o arquivo por `fileURL`. - Compatibilidade futura: o retorno em base64 poderá ser limitado para arquivos maiores que 5 MB. Não dependa de base64 para arquivos grandes. - Transcrição requer chave OpenAI válida. A chave pode ser configurada uma vez na instância e será reutilizada automaticamente. - Retenção de mídia: o arquivo fica disponível no nosso CDN por 2 dias. Depois disso, `fileURL` deixa de funcionar. Chame este endpoint novamente para gerar uma nova URL, enquanto a mensagem e a mídia original ainda estiverem disponíveis. - Para conservar a mídia por mais de 2 dias, baixe o arquivo pela `fileURL` e salve-o em um armazenamento próprio. Guardar somente a URL não aumenta o prazo de retenção. # Edita uma mensagem enviada Source: https://docs.wppfy.com/pt-br/api-reference/message-actions-and-search/edit-a-sent-message /openapi-pt-BR.json post /message/edit Edita o conteúdo de uma mensagem já enviada usando a funcionalidade nativa do WhatsApp. Use esta operação para corrigir o texto de uma mensagem enviada pela própria instância. A resposta retorna a mensagem atualizada e a alteração também aparece nos eventos configurados. **Importante**: - Só é possível editar mensagens enviadas pela própria instância - A mensagem precisa estar disponível no histórico da instância - O ID pode ser fornecido no formato completo retornado pela API ou apenas como `messageid` - A mensagem deve estar dentro do prazo permitido pelo WhatsApp para edição - Para newsletters/canais, use `POST /newsletter/messages/edit` # Status da mensagem em grupo Source: https://docs.wppfy.com/pt-br/api-reference/message-actions-and-search/group-message-status /openapi-pt-BR.json post /message/status Mostra quem recebeu e quem leu uma mensagem que você enviou num grupo: primeiro um resumo com os totais, depois a lista de cada participante. `source` diz de onde veio a resposta. - `source: "memory"`: depois que esta rota é usada para um grupo, a API passa a acompanhar em memória as confirmações dos grupos da instância, até 24 horas depois da última consulta. Respondem daí, na hora e sem depender do celular, as mensagens enviadas a partir de então e as que o celular já respondeu, com as confirmações que chegaram depois somadas. Cada mensagem fica até 24 horas na memória; em instâncias com muito envio para grupos, as mais antigas saem antes. - `source: "phone"`: a primeira consulta de uma mensagem enviada antes disso, ou de qualquer mensagem depois de um reinício do servidor, pergunta ao celular da conta. O celular precisa estar ligado e com internet. Com o WhatsApp aberto, a resposta vem em cerca de 1 segundo; com o celular parado (um iPhone em segundo plano, por exemplo), ela pode não vir. Sem resposta em 40 segundos, a rota retorna `504`. A lista é a que o celular guarda: logo depois de ficar sem internet, ele pode responder antes de receber as confirmações que chegaram nesse meio-tempo. - `summary`: quantos participantes receberam (`delivered`) e leram (`read`). Quem leu também conta como recebido, e quem ouviu um áudio ou vídeo conta como lido. - `receipts`: um item por participante e estado, em ordem de horário e em páginas, como nas outras listas da API: para a próxima, envie o `pagination.nextOffset` em `offset` enquanto `pagination.hasMore` for `true`. O resumo vem em todas. - Quem leu pode vir sem o item `Delivered`, quando o celular não guardou a hora da entrega. - `state` filtra a lista por estado: `Delivered`, `Read` ou `Played`. O resumo continua com os totais da mensagem. - `id` aceita o ID completo ou o curto da mensagem, que precisa estar no histórico da instância. - A API não grava as confirmações em banco. Para acompanhá-las ao vivo, use o webhook `messages_update` com `type: "GroupReceipts"`. # Marcar mensagens como lidas Source: https://docs.wppfy.com/pt-br/api-reference/message-actions-and-search/mark-messages-as-read /openapi-pt-BR.json post /message/markread Marca uma ou mais mensagens como lidas. Este endpoint permite: 1. Marcar múltiplas mensagens como lidas de uma vez 2. Atualizar o status de leitura no WhatsApp 3. Sincronizar o status de leitura entre dispositivos Exemplo de requisição básica: ```json { "id": [ "62AD1AD844E518180227BF68DA7ED710", "ECB9DE48EB41F77BFA8491BFA8D6EF9B" ] } ``` Exemplo de resposta: ```json { "success": true, "message": "Messages marked as read", "markedMessages": [ { "id": "62AD1AD844E518180227BF68DA7ED710", "timestamp": 1672531200000 }, { "id": "ECB9DE48EB41F77BFA8491BFA8D6EF9B", "timestamp": 1672531300000 } ] } ``` Parâmetros disponíveis: - id: Lista de IDs das mensagens a serem marcadas como lidas Erros comuns: - 401: Token inválido ou expirado - 400: Lista de IDs vazia ou inválida - 404: Uma ou mais mensagens não encontradas - 500: Erro ao marcar mensagens como lidas # Fixa ou desafixa uma mensagem Source: https://docs.wppfy.com/pt-br/api-reference/message-actions-and-search/pins-or-unpins-a-message /openapi-pt-BR.json post /message/pin Fixa ou desafixa uma mensagem específica usando a funcionalidade nativa do WhatsApp. Use esta operação para destacar uma mensagem importante em uma conversa individual ou grupo. A resposta registra a ação e ela também aparece nos eventos configurados. **Importante**: - O ID pode ser fornecido no formato completo retornado pela API ou apenas como `messageid` - Em conversas `1:1`, a ação é suportada normalmente - Em grupos, a permissão depende da configuração do WhatsApp do grupo (`apenas admins` ou `qualquer membro`) - Em grupos, a permissão final depende das configurações do próprio grupo - Newsletters/canais não são suportados neste endpoint - Se `pin` não for enviado, o valor padrão é `true` - Ao fixar mensagem, `duration` aceita dias (`1`, `7` ou `30`) - Se `duration` não for enviado ou vier com qualquer outro valor, a API usa `30` dias - Ao desafixar (`pin: false`), `duration` é ignorado # Recuperar mensagem que não abriu Source: https://docs.wppfy.com/pt-br/api-reference/message-actions-and-search/recover-message-that-did-not-open /openapi-pt-BR.json post /message/reload Pede ao celular conectado uma nova cópia de uma mensagem que chegou sem abrir. Quando uma mensagem chega e não pode ser aberta, a API já pede uma cópia ao celular automaticamente. Se a cópia não vier, a mensagem fica salva com `messageType: "error"` no `/message/find`, sem o conteúdo original. Vale também para Status de contatos (`chatid: status@broadcast`). Use esta rota para tentar de novo, por exemplo depois de abrir o WhatsApp no celular. Regras: - envie o `id` que o `/message/find` devolve ou o `messageid` - a mensagem precisa estar salva na instância; se não estiver, a resposta é `404` - ligações (`messageType: call`) não podem ser pedidas Resultado: - a resposta só confirma que o pedido foi enviado ao celular - se o celular tiver a mensagem, ela chega depois como uma mensagem nova: webhook/SSE `messages` (`status_posts` para Status), e a linha do `/message/find` passa a ter o conteúdo, com o mesmo `messageid` - se a cópia não chegar, nada muda e não há aviso de falha - **Importante:** a recuperação pode só acontecer depois de abrir o WhatsApp no celular ou deixá-lo ativo em segundo plano Só mensagens que não abriram são recuperadas. Para uma mensagem já salva normalmente, a cópia que o celular reenvia é descartada como repetida, sem webhook nem alteração. Logo depois de conectar, enquanto o histórico inicial ainda está sendo processado, essa cópia pode chegar de novo como mensagem nova. Para buscar mensagens antigas que ainda não estão salvas, use `POST /message/history-sync`. # Solicitar histórico sob demanda de um chat Source: https://docs.wppfy.com/pt-br/api-reference/message-actions-and-search/request-on-demand-history-for-a-chat /openapi-pt-BR.json post /message/history-sync Solicita ao WhatsApp um sync sob demanda de mensagens antigas de um chat, para trás a partir de uma mensagem de referência (âncora). Para recuperar uma mensagem salva que não abriu (`messageType: "error"` no `/message/find`), use `POST /message/reload`. Regras: - envie `number` - `count` é opcional e limitado a 100 - `messageid` é opcional; quando informado, a API usa essa mensagem como referência para buscar mensagens mais antigas do chat Observação: - **Importante:** a recuperação pode só acontecer depois de abrir o WhatsApp no celular ou deixá-lo ativo em segundo plano - `messageid` define a mensagem de referência para carregar histórico anterior; esse campo não serve para buscar essa mensagem específica - se você quiser recuperar apenas uma mensagem específica `X` via histórico, informe como `messageid` a mensagem logo depois de `X` e use `count=1` - se `messageid` não for informado, a API usa a mensagem mais antiga conhecida localmente desse chat como referência para buscar histórico anterior - as mensagens retornam depois via webhook/SSE em eventos do tipo `history` e também ficam disponíveis em `/message/find` ## Resultado A resposta traz o `request_id` do pedido. As mensagens chegam no webhook/SSE `history` com `event: "messages"` e o `request_id` em cada mensagem. Ele também vem no topo dos lotes `messages` e `chats` quando todo o lote pertence ao mesmo pedido; lotes mistos podem omiti-lo no topo. O pedido termina com um único lote `event: "status"` com o mesmo `request_id`: - `status`: `completed` quando o WhatsApp confirma a conclusão do pedido, `timeout` quando não houve resposta conclusiva em 2 minutos, `blocked` quando o celular indica mais mensagens, mas não entregou uma página que avance - `success` e `error`: só quando não há próxima página possível; `success: false` e o motivo em `error` (`pagination_no_progress`, `anchor_unavailable`, `history_access_unavailable` ou `cursor_lookup_failed`). Sempre vêm com `blocked` - `has_more`: o que o celular declarou. `true` há mais mensagens no celular, `false` chegou ao início da conversa, `null` não foi confirmado. Alguns aparelhos declaram `true` em toda resposta sob demanda, inclusive na vazia: com eles, a paginação termina em `blocked` com `pagination_no_progress`, nunca em `has_more: false` - `history_access`: `unavailable` quando há mais mensagens, mas o WhatsApp não dá acesso a elas - `next_request`: corpo pronto para pedir as mensagens anteriores; reenvie como veio. `null` quando não há uma próxima requisição utilizável Para paginar, reenvie `next_request` do resultado final até ele vir `null`, aguardando o resultado de cada pedido. `completed` encerra o pedido, não toda a conversa. `next_request: null` sem `has_more: false` não comprova o início da conversa. Silêncio ou um lote com menos mensagens que `count` não indicam o fim do histórico: só `has_more: false` indica. Com `blocked` e `error: "pagination_no_progress"`, encerre a paginação desse chat sem repetir o pedido automaticamente: é o fim do que o celular entrega a partir daquela âncora, e repetir dá o mesmo resultado. Cada chat tem um pedido ativo por vez. Repetir o pedido com a mesma mensagem de referência antes do `status` devolve o mesmo `request_id` (`details.reused: true`), sem novo envio ao celular. Um pedido com outra referência encerra o anterior, que recebe o próprio `status` final (em geral `timeout`), e segue normalmente. `409` só ocorre quando o `requestId` informado já está em uso. O resultado final chega por webhook/SSE em até 2 minutos após enviar o pedido ao WhatsApp (`details.result_timeout_ms`). Mensagens atrasadas podem continuar chegando com o mesmo `request_id` por cerca de 5 minutos após o pedido, sem um segundo status final. ## Modo síncrono (`sync: true`) `sync: true` segura a resposta até o resultado, por até `timeoutMs` (padrão e máximo 25000). As mensagens vêm em `messages`, e o topo da resposta traz os mesmos campos do `status` final (`status`, `has_more`, `history_access`, `received_messages`, `next_request`), além de `received`, `timed_out` e `partial`: - resultado final dentro do prazo: `200` com esse resultado; - chegaram mensagens, mas não o resultado: `200` com `status: "pending"`, cerca de 2 segundos depois da última mensagem; - nada chegou no prazo: `202` com `status: "pending"`, `timed_out: true` e `messages` vazio. Com `status: "pending"`, o resultado final chega depois pelo webhook/SSE `history`, com o mesmo `request_id`. O webhook e o SSE são enviados também no modo síncrono, e as mensagens são salvas do mesmo jeito. ## Mensagem de referência apagada Se a âncora foi apagada, a API tenta usar a próxima mensagem válida desse chat. `details.requested_anchor_messageid` informa a referência solicitada, `details.anchor_messageid` a usada e `details.anchor_replaced` indica a substituição. Sem alternativa, retorna HTTP `400` com `status: "anchor_unavailable"`; tente sem `messageid` para usar a mensagem mais antiga salva. # Buscar mensagens em um chat Source: https://docs.wppfy.com/pt-br/api-reference/message-actions-and-search/search-messages-in-a-chat /openapi-pt-BR.json post /message/find Busca mensagens com múltiplos filtros disponíveis. Este endpoint permite: 1. **Busca por ID específico**: Use `id` para encontrar uma mensagem exata 2. **Filtrar por chat**: Use `chatid` para mensagens de uma conversa específica 3. **Filtrar por rastreamento**: Use `track_source` e `track_id` para mensagens com dados de tracking 4. **Histórico de ligações**: Use apenas `messageType: call`, `limit` e `offset` para listar as chamadas mais recentes. A resposta pode trazer `callPeer` (identidade conhecida do contato) e `content.isVideo`. 5. **Status dos contatos**: Use `chatid: status@broadcast` para os Status recebidos, mesmo sem webhook `status_posts`. Sem esse `chatid`, a busca não traz Status. Eles ficam guardados por 24 horas, como no WhatsApp (a limpeza roda uma vez por dia, então filtre `messageTimestamp` se precisar do corte exato), e o Status que o autor apaga sai da lista. Cada um vem com o autor em `sender_pn`, `sender_lid` e `sender_image_preview_url` (foto, quando conhecida) e, nos de imagem, vídeo ou link, com a miniatura em `content.JPEGThumbnail`. Baixe a mídia pelo `/message/download`. Um Status que não abriu vem com `messageType: error` e só o ID, o autor e o horário. **Status de grupo** (enviados e recebidos) ficam na conversa de cada grupo com `messageType: GroupStatusMessage` e o texto em `text`: liste todos com `messageType: GroupStatusMessage`, sem `chatid`. Saem em 24 horas, como os outros Status. 6. **Limitar resultados**: Use `limit` para controlar quantas mensagens retornar 7. **Ordenação**: Resultados ordenados por data (mais recentes primeiro) Fora dos Status, as mensagens guardadas só trazem no `content` as miniaturas em base64 que não têm cópia no servidor (prévia de link sem cópia, localização, anúncio, convites); as de mídia que pode ser baixada de novo (`JPEGThumbnail` e afins) chegam só no webhook, na hora da mensagem. Nas mensagens enviadas pela API nos últimos 7 dias, `sendPayload` traz o pedido de envio, sem os arquivos em base64 (links vêm). Depois do envio (em conversa individual, 1 hora depois), o arquivo em base64 guardado vira o texto `[arquivo removido após o envio: tipo, N bytes]`. # Enviar reação a uma mensagem Source: https://docs.wppfy.com/pt-br/api-reference/message-actions-and-search/send-reaction-to-a-message /openapi-pt-BR.json post /message/react Envia uma reação (emoji) a uma mensagem específica. Informe apenas `id` e `text`. O chat e o autor da mensagem alvo são obtidos da mensagem salva na instância. O campo legado `number` é opcional e ignorado. Este endpoint permite: 1. Adicionar ou remover reações em mensagens 2. Usar qualquer emoji Unicode válido 3. Reagir a mensagens em chats individuais ou grupos 4. Remover reações existentes 5. Verificar o status da reação enviada Tipos de reações suportados: - Qualquer emoji Unicode válido (👍, ❤️, 😂, etc) - String vazia para remover reação Exemplo de requisição básica: ```json { "text": "👍", "id": "3EB0538DA65A59F6D8A251" } ``` Exemplo de requisição para remover reação: ```json { "text": "", "id": "3EB0538DA65A59F6D8A251" } ``` Exemplo de resposta: ```json { "success": true, "message": "Reaction sent", "reaction": { "id": "3EB0538DA65A59F6D8A251", "emoji": "👍", "timestamp": 1672531200000, "status": "sent" } } ``` Exemplo de resposta ao remover reação: ```json { "success": true, "message": "Reaction removed", "reaction": { "id": "3EB0538DA65A59F6D8A251", "emoji": null, "timestamp": 1672531200000, "status": "removed" } } ``` Parâmetros disponíveis: - text: Emoji Unicode da reação (ou string vazia para remover reação) - id: ID da mensagem que receberá a reação Erros comuns: - 401: Token inválido ou expirado - 400: ID ausente ou dados inválidos - 404: Mensagem não encontrada - 500: Erro ao enviar reação Limitações: - Só é possível reagir a mensagens enviadas por outros usuários - Não é possível reagir a mensagens antigas (mais de 7 dias) - O mesmo usuário só pode ter uma reação ativa por mensagem # Aceitar convite de admin do canal Source: https://docs.wppfy.com/pt-br/api-reference/newsletters-and-channels/accept-channel-admin-invitation /openapi-pt-BR.json post /newsletter/admin/accept Aceita um convite pendente e torna a conta conectada administradora do canal informado. # Criar canal Source: https://docs.wppfy.com/pt-br/api-reference/newsletters-and-channels/create-channel /openapi-pt-BR.json post /newsletter/create Cria um novo canal/newsletter no WhatsApp. Observações: - `name` é obrigatório - `picture` é opcional - `picture` aceita URL HTTP/HTTPS, base64 puro ou data URI - imagens acima de 1 MB são rejeitadas # Deletar canal Source: https://docs.wppfy.com/pt-br/api-reference/newsletters-and-channels/delete-channel /openapi-pt-BR.json post /newsletter/delete Exclui um canal administrado pela conta conectada. Para apenas parar de acompanhar um canal, use a operação de deixar de seguir. # Deletar mensagem recente de um canal Source: https://docs.wppfy.com/pt-br/api-reference/newsletters-and-channels/delete-recent-channel-message /openapi-pt-BR.json post /newsletter/messages/delete Apaga um post recente de newsletter diretamente no WhatsApp. Esta rota: - nao depende de mensagens salvas localmente - revoga o post diretamente no canal do WhatsApp - aceita localizar o post por `messageid` ou `serverid` Observações: - use `jid` para identificar o canal - envie ao menos um entre `messageid` e `serverid` - `count` e `maxpages` controlam a janela de busca no canal # Editar mensagem recente de um canal Source: https://docs.wppfy.com/pt-br/api-reference/newsletters-and-channels/edit-recent-channel-message /openapi-pt-BR.json post /newsletter/messages/edit Edita o conteúdo de um post recente de newsletter diretamente no WhatsApp. Esta rota: - nao depende de mensagens salvas localmente - busca a mensagem recente diretamente no canal do WhatsApp - localiza o post por `messageid` ou `serverid` - edita apenas tipos suportados (`text`, `image`, `video`, `document`) Observações: - use `jid` para identificar o canal - envie ao menos um entre `messageid` e `serverid` - envie `text` ou `caption` com o novo conteúdo/legenda - para posts de mídia, `mediahandle` pode informar o handle já conhecido - `count` e `maxpages` controlam a janela de busca no canal # Buscar updates de mensagens de um canal Source: https://docs.wppfy.com/pt-br/api-reference/newsletters-and-channels/fetch-channel-message-updates /openapi-pt-BR.json post /newsletter/updates **Obsoleta.** O WhatsApp não responde à consulta de updates (`message_updates`): a API desiste em 10 segundos e responde 504. Para views e reações dos posts, use `POST /newsletter/messages`, que traz `viewsCount` e `reactionCounts` em cada post. Parâmetros mantidos por compatibilidade: - `afterid` filtra updates depois de um `serverid` - `since` filtra pelo momento do update, em segundos ou milissegundos # Buscar mensagens de um canal Source: https://docs.wppfy.com/pt-br/api-reference/newsletters-and-channels/fetch-channel-messages /openapi-pt-BR.json post /newsletter/messages Busca diretamente no WhatsApp os posts/mensagens de um canal (newsletter). Esta rota não depende de mensagens salvas localmente e é útil para: - carregar o histórico recente de posts de um canal - paginar mensagens anteriores usando `beforeid` - consumir conteúdo de newsletters sem persistência em banco Identificação do canal: - envie `id` com o identificador numérico do canal; a API normaliza para `@newsletter` - ou envie `jid` completo no formato `1234567890@newsletter` Observações: - `count` controla quantos posts retornar - use preferencialmente `beforeid` - `beforeid` pagina para trás a partir de um `serverid` - o retorno vem no campo `response` # Buscar canal por link-chave de convite Source: https://docs.wppfy.com/pt-br/api-reference/newsletters-and-channels/find-channel-by-invite-key-link /openapi-pt-BR.json post /newsletter/link Resolve uma chave de convite e apresenta as informações do canal antes da entrada, sem exigir que a conta já siga esse canal. # Seguir canal Source: https://docs.wppfy.com/pt-br/api-reference/newsletters-and-channels/follow-channel /openapi-pt-BR.json post /newsletter/follow Faz a conta conectada seguir um canal, que então passa a aparecer na listagem e fica disponível para consulta de posts. # Buscar informações de um canal Source: https://docs.wppfy.com/pt-br/api-reference/newsletters-and-channels/get-channel-information /openapi-pt-BR.json post /newsletter/info Retorna nome, descrição, imagem e demais informações disponíveis de um canal pelo `jid`. Use antes de exibir o canal ou executar ações administrativas. # Convidar admin do canal Source: https://docs.wppfy.com/pt-br/api-reference/newsletters-and-channels/invite-channel-admin /openapi-pt-BR.json post /newsletter/admin/invite Envia a um telefone um convite para administrar o canal. O acesso só muda depois que o destinatário aceitar. # Listar canais inscritos Source: https://docs.wppfy.com/pt-br/api-reference/newsletters-and-channels/list-subscribed-channels /openapi-pt-BR.json get /newsletter/list Lista os canais seguidos pela conta conectada. Use para montar uma tela de canais antes de consultar posts, silenciar notificações ou deixar de seguir. # Marcar posts do canal como visualizados Source: https://docs.wppfy.com/pt-br/api-reference/newsletters-and-channels/mark-channel-posts-as-viewed /openapi-pt-BR.json post /newsletter/viewed Marca um ou mais posts do canal como visualizados usando `serverid`. Observações: - envie `serverids` com uma lista de posts # Silenciar canal Source: https://docs.wppfy.com/pt-br/api-reference/newsletters-and-channels/mute-channel /openapi-pt-BR.json post /newsletter/mute Silencia as notificações de um canal sem deixar de segui-lo; os posts continuam disponíveis para consulta. # Reagir a um post do canal Source: https://docs.wppfy.com/pt-br/api-reference/newsletters-and-channels/react-to-a-channel-post /openapi-pt-BR.json post /newsletter/reaction Envia, altera ou remove uma reação de um post do canal. Observações: - `serverid` identifica o post alvo - `reaction` define o emoji - envie `reaction` vazio para remover a reação - `reactionmessageid` é opcional; se omitido, o WhatsApp gera o ID da reação # Remover admin do canal Source: https://docs.wppfy.com/pt-br/api-reference/newsletters-and-channels/remove-channel-admin /openapi-pt-BR.json post /newsletter/admin/remove Remove as permissões administrativas de um participante pelo telefone sem deixar de segui-lo automaticamente. # Revogar convite de admin do canal Source: https://docs.wppfy.com/pt-br/api-reference/newsletters-and-channels/revoke-channel-admin-invite /openapi-pt-BR.json post /newsletter/admin/revoke Cancela um convite de administrador que ainda não foi aceito; administradores ativos não são removidos por esta operação. # Pesquisar canais públicos Source: https://docs.wppfy.com/pt-br/api-reference/newsletters-and-channels/search-public-channels /openapi-pt-BR.json post /newsletter/search Pesquisa canais/newsletters públicos no diretório do WhatsApp pelo texto. Observações: - `searchText` é obrigatório: o WhatsApp só pesquisa o diretório por texto - sem `searchText`, a API responde 400 antes de chamar o WhatsApp - não há filtro por país nem listagem por categoria: o WhatsApp recusa busca sem texto, com filtro de país ou por `view` - use `after` com o valor de `response.after` para buscar a próxima página - quando `response.after` vier `null`, não há mais páginas # Assinar live updates temporários de um canal Source: https://docs.wppfy.com/pt-br/api-reference/newsletters-and-channels/subscribe-to-temporary-live-updates-of-a-channel /openapi-pt-BR.json post /newsletter/subscribe Assina temporariamente os live updates internos do WhatsApp para um canal. Observação: - esta rota retorna apenas a duração da assinatura temporária - isso não cria um novo evento de webhook # Transferir dono do canal Source: https://docs.wppfy.com/pt-br/api-reference/newsletters-and-channels/transfer-channel-owner /openapi-pt-BR.json post /newsletter/owner/transfer Transfere a propriedade do canal para outro telefone. Observações: - `phone` é obrigatório - `quitAdmin=true` remove o dono anterior da posição de admin após a transferência # Deixar de seguir canal Source: https://docs.wppfy.com/pt-br/api-reference/newsletters-and-channels/unfollow-channel /openapi-pt-BR.json post /newsletter/unfollow Remove o canal da lista seguida pela conta conectada sem apagar o canal nem seus posts. # Remover mute do canal Source: https://docs.wppfy.com/pt-br/api-reference/newsletters-and-channels/unmute-channel /openapi-pt-BR.json post /newsletter/unmute Reativa as notificações de um canal anteriormente silenciado, mantendo a inscrição e o histórico disponíveis. # Atualizar descrição do canal Source: https://docs.wppfy.com/pt-br/api-reference/newsletters-and-channels/update-channel-description /openapi-pt-BR.json post /newsletter/description Atualiza a descrição pública do canal para explicar o tema, a frequência e o conteúdo publicado. # Atualizar nome do canal Source: https://docs.wppfy.com/pt-br/api-reference/newsletters-and-channels/update-channel-name /openapi-pt-BR.json post /newsletter/name Altera o nome público de um canal administrado pela conta conectada, facilitando sua identificação pelos participantes. # Atualizar foto do canal Source: https://docs.wppfy.com/pt-br/api-reference/newsletters-and-channels/update-channel-picture /openapi-pt-BR.json post /newsletter/picture Atualiza a imagem do canal/newsletter. Observações: - `picture` aceita URL HTTP/HTTPS, base64 puro ou data URI - imagens acima de 1 MB são rejeitadas # Atualizar configurações do canal Source: https://docs.wppfy.com/pt-br/api-reference/newsletters-and-channels/update-channel-settings /openapi-pt-BR.json post /newsletter/settings Atualiza configurações do canal/newsletter. Atualmente, esta rota controla `reactionCodes`. Valores aceitos: - `all` - `basic` - `none` - `blocklist` # Altera a imagem do perfil do WhatsApp Source: https://docs.wppfy.com/pt-br/api-reference/profile/change-whatsapp-profile-image /openapi-pt-BR.json post /profile/image Altera a imagem de perfil da conta do WhatsApp atualmente conectada. O endpoint realiza: - Atualiza a imagem do perfil usando - Processa a imagem (URL, base64 ou comando de remoção) - Sincroniza a mudança com o servidor do WhatsApp - Retorna confirmação da alteração **Importante**: - A conta do WhatsApp deve estar conectada - A imagem será visível para todos os contatos - A imagem deve estar em formato JPEG e tamanho 640x640 pixels # Altera o nome do perfil do WhatsApp Source: https://docs.wppfy.com/pt-br/api-reference/profile/change-whatsapp-profile-name /openapi-pt-BR.json post /profile/name Altera o nome de exibição do perfil da conta do WhatsApp atualmente conectada. O endpoint realiza: - Atualiza o nome do perfil usando o WhatsApp AppState - Sincroniza a mudança com o servidor do WhatsApp - Retorna confirmação da alteração **Importante**: - A conta do WhatsApp deve estar conectada - O nome será visível para todos os contatos - Pode haver um limite de alterações por período (conforme WhatsApp) # Configurar ou alterar o proxy Source: https://docs.wppfy.com/pt-br/api-reference/proxy/configure-or-change-the-proxy /openapi-pt-BR.json post /instance/proxy Define explicitamente um dos três estados aceitos: - `mode=custom`: usa um proxy próprio informado em `proxy_url`; - `mode=internal`: usa a infraestrutura interna; ou - `mode=none`: conexão direta, permitida apenas com `confirm_no_proxy=true`. Importante: `POST /instance/proxy` confirma que a configuração foi salva, não que o proxy já foi comprovado em uso. A validação operacional principal acontece no próximo ciclo real de conexão da instância. Em termos práticos: - `200 OK` aqui = configuração persistida com sucesso; - falhas reais de conectividade podem aparecer depois; e - para observar o estado real, consulte `GET /instance/proxy` e leia: - `effective_mode` - `effective_detail` - `fallback.active` - `last_test_error` - `validation_error` Quando `mode=custom`, você também pode definir a contingência via `proxy_fallback`: - `internal`: tenta a infraestrutura interna e, se ainda assim falhar, pode usar direto como último recurso; - `never`: não usa contingência; ou - uma URL de proxy de contingência controlada pelo próprio cliente. Quando `mode=internal`, `rotate_now: true` troca imediatamente o proxy interno persistido. Se houver mais de uma origem interna disponível, a plataforma escolhe outra origem sem expor o fornecedor. Se houver apenas uma origem, troca apenas o proxy/IP dentro dessa origem. Protocolos aceitos em URLs de proxy customizado: - `http://usuario:senha@host:porta` - `https://usuario:senha@host:porta` - `socks5://usuario:senha@host:porta` - `socks5h://usuario:senha@host:porta` O esquema `socks://` genérico não é aceito. Para proxies SOCKS, use `socks5://` ou `socks5h://`. # Obter configuração de proxy da instância Source: https://docs.wppfy.com/pt-br/api-reference/proxy/get-instance-proxy-configuration /openapi-pt-BR.json get /instance/proxy Mostra a configuração desejada e a rota de conexão usada pela instância no momento. Use para confirmar se o proxy escolhido está ativo ou se uma rota alternativa foi aplicada para preservar a conexão. - `mode` informa a configuração escolhida: `custom`, `internal` ou `none`. - `effective_mode` informa a conexão em uso: `custom`, `internal` ou `direct`. - `fallback.active` indica que a rota principal não está disponível. - `proxy_url` retorna a URL configurada com credenciais mascaradas. - `last_test_error` ajuda a diagnosticar a última falha conhecida. Em condições normais, `mode` e `effective_mode` correspondem. Durante uma contingência, eles podem divergir sem alterar a preferência salva. Não use este endpoint em polling contínuo; acompanhe também `GET /instance/status`. # Proxy Interno - Listar cidades disponíveis Source: https://docs.wppfy.com/pt-br/api-reference/proxy/internal-proxy-list-available-cities /openapi-pt-BR.json get /proxy-managed/cities Retorna a lista de cidades disponíveis para uso nos campos `proxy_managed_country`, `proxy_managed_state` e `proxy_managed_city` dos endpoints `POST /instance/connect`. Respostas de sucesso enviam `Cache-Control: public, max-age=300`. Se o catálogo de cidades estiver temporariamente indisponível, tente novamente depois do intervalo indicado pela resposta. - Autenticação: endpoint público, sem `token`. - Proteção: limite de 120 requisições por minuto por IP; excesso retorna `429` com `Retry-After`. - Query `country` (opcional): ISO alpha-2 minúsculo. Default `br`. - Query `state` (opcional): UF/subdivisão minúscula, como `sp`. - Query `search` (opcional): filtro parcial por nome/slug, insensível a acento/caixa. Como escolher a cidade: 1. Use `br` em `proxy_managed_country`. 2. Chame `GET /proxy-managed/cities?country=br` para obter as cidades brasileiras. 3. Quando a cidade retornar `state`, envie também esse valor em `proxy_managed_state`. 4. Quando o usuário escolher uma cidade, envie em `/instance/connect`: - `proxy_managed_country`: o país escolhido, ex. `br` - `proxy_managed_state`: o `state` retornado pela cidade, ex. `sp`, quando disponível - `proxy_managed_city`: sempre o `cities[].value` Se `state` não vier na cidade selecionada, envie apenas `proxy_managed_country` e `proxy_managed_city`. A API valida a combinação e retorna erro se faltar algum dado necessário. Exemplo de requisição: ``` GET /proxy-managed/cities?country=br&state=sp&search=camp ``` # Proxy Interno - Listar países disponíveis Source: https://docs.wppfy.com/pt-br/api-reference/proxy/internal-proxy-list-available-countries /openapi-pt-BR.json get /proxy-managed/countries Retorna a lista de países aceitos pelo campo `proxy_managed_country` de `POST /instance/connect`. Respostas de sucesso enviam `Cache-Control: public, max-age=300`. Quando o catálogo estiver temporariamente indisponível, o endpoint responde `503`. - Autenticação: endpoint público, sem `token`. - Proteção: limite de 120 requisições por minuto por IP; excesso retorna `429` com `Retry-After`. - Sem parâmetros de query. Os valores retornados em `countries[].value` são exatamente os aceitos em `proxy_managed_country` no `/instance/connect`. Os valores em `countries[].label` são apenas rótulos para exibição; envie sempre o campo `value` nas operações de criação ou conexão. Exemplo de requisição: ``` GET /proxy-managed/countries ``` # Solicitar pagamento Source: https://docs.wppfy.com/pt-br/api-reference/send-message/request-payment /openapi-pt-BR.json post /send/request-payment Envia uma solicitação de pagamento com o botão nativo **"Revisar e pagar"** do WhatsApp. O fluxo suporta PIX (estático, dinâmico ou desabilitado), boleto, link de pagamento e cartão, combinando tudo em uma única mensagem interativa. ## Como funciona - Define o valor em `amount` (BRL por padrão) e opcionalmente personaliza título, texto e nota adicional. - Por padrão exige `pixKey`. - O arquivo apontado por `fileUrl` é anexado como documento (boleto ou fatura em PDF, por exemplo). - `paymentLink` habilita o botão externo. - Para cobrar um pedido recebido pelo WhatsApp, informe `orderMessageId` com o ID da mensagem `OrderMessage` desse mesmo contato. A API obtém itens, moeda e total do pedido; `amount` não é necessário nesse caso. Ainda é preciso informar um método de pagamento. ## Campos comuns Este endpoint também suporta os campos padrão: `delay`, `readchat`, `readmessages`, `replyid`, `mentions`, `track_source`, `track_id` e `async`. # Solicitar localização do usuário Source: https://docs.wppfy.com/pt-br/api-reference/send-message/request-user-location /openapi-pt-BR.json post /send/location-button Este endpoint envia uma mensagem com um botão que solicita a localização do usuário. Quando o usuário clica no botão, o WhatsApp abre a interface para compartilhar a localização atual. ## Campos Comuns Este endpoint suporta todos os **campos opcionais comuns** documentados na tag **"Enviar Mensagem"**, incluindo: `delay`, `readchat`, `readmessages`, `replyid`, `mentions`, `forward`, `track_source`, `track_id`, placeholders e envio para grupos. ## Estrutura do Payload ```json { "number": "5511999999999", "text": "Por favor, compartilhe sua localização", "delay": 0, "readchat": true } ``` ## Exemplo de Uso ```json { "number": "5511999999999", "text": "Para continuar o atendimento, clique no botão abaixo e compartilhe sua localização" } ``` > **Nota**: O botão de localização é adicionado automaticamente à mensagem # Enviar cartão de contato (vCard) Source: https://docs.wppfy.com/pt-br/api-reference/send-message/send-contact-card-vcard /openapi-pt-BR.json post /send/contact Envia um cartão de contato (vCard) para um contato ou grupo. ## Recursos Específicos - **vCard completo** com nome, telefones, organização, email e URL - **Múltiplos números de telefone** (separados por vírgula) - **Cartão clicável** no WhatsApp para salvar na agenda - **Informações profissionais** (organização/empresa) ## Campos Comuns Este endpoint suporta todos os **campos opcionais comuns** documentados na tag **"Enviar Mensagem"**, incluindo: `delay`, `readchat`, `readmessages`, `replyid`, `mentions`, `forward`, `track_source`, `track_id`, placeholders e envio para grupos. ## Exemplo Básico ```json { "number": "5511999999999", "fullName": "João Silva", "phoneNumber": "5511999999999,5511888888888", "organization": "Empresa XYZ", "email": "joao.silva@empresa.com", "url": "https://empresa.com/joao" } ``` # Enviar evento Source: https://docs.wppfy.com/pt-br/api-reference/send-message/send-event /openapi-pt-BR.json post /send/event Envia um convite de evento para um contato ou grupo. Informe `startTime` em segundos ou milissegundos Unix; `endTime` é opcional. Uma resposta do convidado chega como mensagem do tipo `EventResponseMessage`, com a escolha em `vote`. Aceita os campos comuns de envio: `replyid`, `mentions`, `delay`, `readchat`, `readmessages`, `async`, `track_source` e `track_id`. # Enviar localização geográfica Source: https://docs.wppfy.com/pt-br/api-reference/send-message/send-geographical-location /openapi-pt-BR.json post /send/location Envia uma localização geográfica para um contato ou grupo. ## Recursos Específicos - **Coordenadas precisas** (latitude e longitude obrigatórias) - **Nome do local** para identificação - **Endereço completo** para exibição detalhada - **Mapa interativo** no WhatsApp para navegação - **Pin personalizado** com nome do local ## Campos Comuns Este endpoint suporta todos os **campos opcionais comuns** documentados na tag **"Enviar Mensagem"**, incluindo: `delay`, `readchat`, `readmessages`, `replyid`, `mentions`, `forward`, `track_source`, `track_id`, placeholders e envio para grupos. ## Exemplo Básico ```json { "number": "5511999999999", "name": "Maracanã", "address": "Av. Pres. Castelo Branco - Maracanã, Rio de Janeiro - RJ", "latitude": -22.912982815767986, "longitude": -43.23028153499254 } ``` # Enviar menu interativo (botões, carrossel, lista ou enquete) Source: https://docs.wppfy.com/pt-br/api-reference/send-message/send-interactive-menu-buttons-carousel-list-or-poll /openapi-pt-BR.json post /send/menu Este endpoint oferece uma interface unificada para envio de quatro tipos principais de mensagens interativas: - Botões: Para ações rápidas e diretas - Carrossel de botões: Para uma lista horizontal de botões com imagens - Listas: Para menus organizados em seções - Enquetes: Para coleta de opiniões e votações **Suporte a campos de rastreamento**: Este endpoint também suporta `track_source` e `track_id` documentados na tag **"Enviar Mensagem"**. ## Estrutura Base do Payload Todas as requisições seguem esta estrutura base: ```json { "number": "5511999999999", "type": "button|button_legacy|list|poll|carousel", "text": "Texto principal da mensagem", "choices": ["opções baseadas no tipo escolhido"], "footerText": "Texto do rodapé (opcional para botões e listas)", "listButton": "Texto do botão (para listas)", "selectableCount": "Número de opções selecionáveis (apenas para enquetes)" } ``` ## Tipos de Mensagens Interativas ### 1. Botões (type: "button") Cria botões interativos com diferentes funcionalidades de ação. #### Campos Específicos - `footerText`: Texto opcional exibido abaixo da mensagem principal - `choices`: Array de opções que serão convertidas em botões #### Formatos de Botões Cada botão pode ser configurado usando `|` (pipe) ou `\n` (quebra de linha) como separadores: - **Botão de Resposta**: - `"texto|id"` ou - `"texto\nid"` ou - `"texto"` (ID será igual ao texto) - **Botão de Cópia**: - `"texto|copy:código"` ou - `"texto\ncopy:código"` - **Botão de Chamada**: - `"texto|call:+5511999999999"` ou - `"texto\ncall:+5511999999999"` - **Botão de URL**: - `"texto|https://exemplo.com"` ou - `"texto|url:https://exemplo.com"` #### Botões com imagem, vídeo ou documento O cabeçalho do botão pode levar uma imagem, um vídeo ou um documento em `file`, por URL ou base64, como no `/send/media`. O tipo sai do próprio arquivo; para forçar, mande `mimetype`: `image`, `video`, `document` ou o MIME type do arquivo (por exemplo, `video/mp4`). O documento usa o nome de `docName`; sem ele, o nome do arquivo. Áudio não vai no botão: o WhatsApp não tem áudio no cabeçalho, e a API responde `400`. Envie o áudio antes, com o `/send/media`. Sem `mimetype`, a API reconhece o áudio pela extensão da URL ou pelo início do base64; numa URL sem extensão, informe o `mimetype`. ```json { "number": "5511999999999", "type": "button", "text": "Escolha um produto:", "file": "https://exemplo.com/produto1.jpg", "choices": [ "Produto A|prod_a", "Mais Info|https://exemplo.com/produto-a", "Produto B|prod_b", "Ligar|call:+5511999999999" ], "footerText": "Produtos em destaque" } ``` ```json { "number": "5511999999999", "type": "button", "text": "Tabela de preços de outubro", "file": "https://exemplo.com/tabela.pdf", "docName": "Tabela de preços.pdf", "choices": ["Quero comprar|comprar", "Falar com vendedor|vendedor"] } ``` Se a mídia não baixar ou não subir para o WhatsApp, o botão sai sem ela. #### Botões no formato legado (type: "button_legacy") Use `button_legacy` somente quando precisar enviar os botões de resposta do formato anterior. O formato de `choices` é: - `"texto|id"` - `"texto\nid"` - `"texto|reply:id"` - `"texto"` — o próprio texto será usado como ID Este modo cria apenas botões de resposta. Ações de URL, chamada e cópia e o a mídia em `file` continuam disponíveis no formato atual `type: "button"`. ```json { "number": "5511999999999", "type": "button_legacy", "text": "Deseja continuar?", "choices": [ "Sim|confirmar", "Não|reply:cancelar" ], "footerText": "Escolha uma opção" } ``` #### Exemplo Completo ```json { "number": "5511999999999", "type": "button", "text": "Como podemos ajudar?", "choices": [ "Suporte Técnico|suporte", "Fazer Pedido|pedido", "Nosso Site|https://exemplo.com", "Falar Conosco|call:+5511999999999" ], "footerText": "Escolha uma das opções abaixo" } ``` #### Limitações e Compatibilidade > **Importante**: Ao combinar botões de resposta com outros tipos (call, url, copy) na mesma mensagem, será exibido o aviso: "Não é possível exibir esta mensagem no WhatsApp Web. Abra o WhatsApp no seu celular para visualizá-la." ### 2. Listas (type: "list") Cria menus organizados em seções com itens selecionáveis. #### Campos Específicos - `listButton`: Texto do botão que abre a lista - `footerText`: Texto opcional do rodapé - `choices`: Array com seções e itens da lista #### Formato das Choices - `"[Título da Seção]"`: Inicia uma nova seção - `"texto|id|descrição"`: Item da lista com: - texto: Label do item - id: Identificador único, opcional - descrição: Texto descritivo adicional e opcional #### Exemplo Completo ```json { "number": "5511999999999", "type": "list", "text": "Catálogo de Produtos", "choices": [ "[Eletrônicos]", "Smartphones|phones|Últimos lançamentos", "Notebooks|notes|Modelos 2024", "[Acessórios]", "Fones|fones|Bluetooth e com fio", "Capas|cases|Proteção para seu device" ], "listButton": "Ver Catálogo", "footerText": "Preços sujeitos a alteração" } ``` ### 3. Enquetes (type: "poll") Cria enquetes interativas para votação. #### Campos Específicos - `selectableCount`: Número de opções que podem ser selecionadas (padrão: 1) - `choices`: Array simples com as opções de voto #### Exemplo Completo ```json { "number": "5511999999999", "type": "poll", "text": "Qual horário prefere para atendimento?", "choices": [ "Manhã (8h-12h)", "Tarde (13h-17h)", "Noite (18h-22h)" ], "selectableCount": 1 } ``` ### 4. Carousel (type: "carousel") Cria um carrossel de cartões com imagens e botões interativos. #### Campos Específicos - `choices`: Array com elementos do carrossel na seguinte ordem: - `[Texto do cartão]`: Texto do cartão entre colchetes - `{URL ou base64 da imagem}`: Imagem entre chaves - Botões do cartão (um por linha): - `"texto|copy:código"` para botão de copiar - `"texto|https://url"` para botão de link - `"texto|call:+número"` para botão de ligação #### Exemplo Completo ```json { "number": "5511999999999", "type": "carousel", "text": "Conheça nossos produtos", "choices": [ "[Smartphone XYZ\nO mais avançado smartphone da linha]", "{https://exemplo.com/produto1.jpg}", "Copiar Código|copy:PROD123", "Ver no Site|https://exemplo.com/xyz", "Fale Conosco|call:+5511999999999", "[Notebook ABC\nO notebook ideal para profissionais]", "{https://exemplo.com/produto2.jpg}", "Copiar Código|copy:NOTE456", "Comprar Online|https://exemplo.com/abc", "Suporte|call:+5511988888888" ] } ``` > **Nota**: Criamos outro endpoint para carrossel: `/send/carousel`, funciona da mesma forma, mas com outro formato de payload. Veja o que é mais fácil para você. ## Termos de uso Os recursos de botões interativos e listas podem ser descontinuados a qualquer momento sem aviso prévio. Não nos responsabilizamos por quaisquer alterações ou indisponibilidade destes recursos. ### Alternativas e Compatibilidade Considerando a natureza dinâmica destes recursos, nosso endpoint foi projetado para facilitar a migração entre diferentes tipos de mensagens (botões, listas e enquetes). Recomendamos criar seus fluxos de forma flexível, preparados para alternar entre os diferentes tipos. Em caso de descontinuidade de algum recurso, você poderá facilmente migrar para outro tipo de mensagem apenas alterando o campo "type" no payload, mantendo a mesma estrutura de choices. # Enviar carrossel de mídia com botões Source: https://docs.wppfy.com/pt-br/api-reference/send-message/send-media-carousel-with-buttons /openapi-pt-BR.json post /send/carousel Este endpoint permite enviar um carrossel com imagens e botões interativos. Funciona de maneira igual ao endpoint `/send/menu` com type: carousel, porém usando outro formato de payload. ## Campos Comuns Este endpoint suporta todos os **campos opcionais comuns** documentados na tag **"Enviar Mensagem"**, incluindo: `delay`, `readchat`, `readmessages`, `replyid`, `mentions`, `forward`, `track_source`, `track_id`, placeholders e envio para grupos. ## Estrutura do Payload ```json { "number": "5511999999999", "text": "Texto principal", "carousel": [ { "text": "Texto do cartão", "image": "URL da imagem", "buttons": [ { "id": "resposta1", "text": "Texto do botão", "type": "REPLY" } ] } ] } ``` ## Tipos de Botões - `REPLY`: Botão de resposta rápida - Quando clicado, envia o valor do id como resposta ao chat - O id será o texto enviado como resposta - `URL`: Botão com link - Quando clicado, abre a URL especificada - O id deve conter a URL completa (ex: https://exemplo.com) - `COPY`: Botão para copiar texto - Quando clicado, copia o texto para a área de transferência - O id será o texto que será copiado - `CALL`: Botão para realizar chamada - Quando clicado, inicia uma chamada telefônica - O id deve conter o número de telefone ## Exemplo de Botões ```json { "buttons": [ { "id": "Sim, quero comprar!", "text": "Confirmar Compra", "type": "REPLY" }, { "id": "https://exemplo.com/produto", "text": "Ver Produto", "type": "URL" }, { "id": "CUPOM20", "text": "Copiar Cupom", "type": "COPY" }, { "id": "5511999999999", "text": "Falar com Vendedor", "type": "CALL" } ] } ``` ## Exemplo Completo de Carrossel ```json { "number": "5511999999999", "text": "Nossos Produtos em Destaque", "carousel": [ { "text": "Smartphone XYZ\nO mais avançado smartphone da linha", "image": "https://exemplo.com/produto1.jpg", "buttons": [ { "id": "SIM_COMPRAR_XYZ", "text": "Comprar Agora", "type": "REPLY" }, { "id": "https://exemplo.com/xyz", "text": "Ver Detalhes", "type": "URL" } ] }, { "text": "Cupom de Desconto\nGanhe 20% OFF em qualquer produto", "image": "https://exemplo.com/cupom.jpg", "buttons": [ { "id": "DESCONTO20", "text": "Copiar Cupom", "type": "COPY" }, { "id": "5511999999999", "text": "Falar com Vendedor", "type": "CALL" } ] } ] } ``` # Enviar mídia (imagem, vídeo, áudio ou documento) Source: https://docs.wppfy.com/pt-br/api-reference/send-message/send-media-image-video-audio-or-document /openapi-pt-BR.json post /send/media Envia diferentes tipos de mídia para um contato, grupo ou canal/newsletter. Suporta URLs ou arquivos base64. ## Tipos de Mídia Suportados - **`image`**: Imagens (JPG preferencialmente) - **`video`**: Vídeos (apenas MP4) - **`videoplay`**: Vídeo com comportamento visual de autoplay/loop no WhatsApp - **`document`**: Documentos (PDF, DOCX, XLSX, etc) - **`audio`**: Áudio comum (MP3 ou OGG) - **`myaudio`**: Mensagem de voz (alternativa ao PTT) - **`ptt`**: Mensagem de voz (Push-to-Talk) - **`ptv`**: Mensagem de vídeo (Push-to-Video) - **`sticker`**: Figurinha/Sticker ## Recursos Específicos - **Upload por URL ou base64** - **Caption/legenda** opcional com suporte a placeholders - **Nome personalizado** para documentos (`docName`) - **Geração automática de thumbnails para imagens e vídeos** quando `thumbnail` não é informado - **Compressão otimizada** conforme o tipo - **`viewOnce`** recomendado para mídia compatível ## Envio para Newsletter Para enviar mídia para um canal, use o mesmo campo `number`, mas informe o JID completo do canal: - Exemplo: `120363123456789012@newsletter` ```json { "number": "120363123456789012@newsletter", "type": "image", "file": "https://exemplo.com/foto.jpg", "text": "Imagem publicada no canal" } ``` ## Campos Comuns Este endpoint suporta todos os **campos opcionais comuns** documentados na tag **"Enviar Mensagem"**, incluindo: `delay`, `readchat`, `readmessages`, `replyid`, `mentions`, `forward`, `track_source`, `track_id`, placeholders e envio para grupos. ## Exemplos Básicos ## Visualização Única (`viewOnce`) O campo `viewOnce` é recomendado quando quiser mídia de visualização única e hoje produz efeito para os tipos: `image`, `video`, `videoplay`, `ptv`, `audio`, `myaudio` e `ptt`. Para `document`, `sticker` e demais endpoints de envio, o campo é ignorado silenciosamente. ## Thumbnail personalizado Use `thumbnail` em `image`, `video`, `videoplay`, `ptv` ou `document`. Aceita URL HTTP/HTTPS, Data URL ou base64 de imagem com até 1 MiB e 4096 px por dimensão. A API converte para JPEG e prioriza essa imagem em relação à miniatura automática. Para documentos, envie uma imagem de pelo menos 480 px para uma prévia mais nítida no WhatsApp Web. Documentos sem `thumbnail` não recebem miniatura automática. Ao reenviar o mesmo documento, reutilize a mesma miniatura: o WhatsApp pode associar a prévia ao conteúdo do arquivo também em mensagens antigas. ### Imagem Simples ```json { "number": "5511999999999", "type": "image", "file": "https://exemplo.com/foto.jpg" } ``` ### Documento com Nome ```json { "number": "5511999999999", "type": "document", "file": "https://exemplo.com/contrato.pdf", "docName": "Contrato.pdf", "text": "Segue o documento solicitado" } ``` # Enviar botão PIX Source: https://docs.wppfy.com/pt-br/api-reference/send-message/send-pix-button /openapi-pt-BR.json post /send/pix-button Envia um botão nativo do WhatsApp que abre para pagamento PIX com a chave informada. O usuário visualiza o detalhe do recebedor, nome e chave. ## Regras principais - `pixType` aceita: `CPF`, `CNPJ`, `PHONE`, `EMAIL`, `EVP` (case insensitive) - `pixName` padrão: `"Pix"` quando não informado - nome de quem recebe o pagamento ## Campos comuns Este endpoint herda os campos opcionais padronizados da tag **"Enviar Mensagem"**: `delay`, `readchat`, `readmessages`, `replyid`, `mentions`, `track_source`, `track_id` e `async`. ## Exemplo de payload ```json { "number": "5511999999999", "pixType": "EVP", "pixKey": "123e4567-e89b-12d3-a456-426614174000", "pixName": "Loja Exemplo" } ``` # Enviar atualização de presença Source: https://docs.wppfy.com/pt-br/api-reference/send-message/send-presence-update /openapi-pt-BR.json post /message/presence Envia uma atualização de presença para um contato ou grupo de forma **assíncrona**. ## 🔄 Comportamento Assíncrono: - **Execução independente**: A presença é gerenciada em background, não bloqueia o retorno da API - **Limite máximo**: 5 minutos de duração (300 segundos) - **Tick de atualização**: Reenvia a presença a cada 10 segundos - **Cancelamento automático**: Presença é cancelada automaticamente ao enviar uma mensagem para o mesmo chat ## 📱 Tipos de presença suportados: - **composing**: Indica que você está digitando uma mensagem - **recording**: Indica que você está gravando um áudio - **paused**: Remove/cancela a indicação de presença atual ## ⏱️ Controle de duração: - **Sem delay**: Usa limite padrão de 5 minutos - **Com delay**: Usa o valor especificado (máximo 5 minutos) - **Cancelamento**: Envio de mensagem cancela presença automaticamente ## 📋 Exemplos de uso: ### Digitar por 30 segundos: ```json { "number": "5511999999999", "presence": "composing", "delay": 30000 } ``` ### Gravar áudio por 1 minuto: ```json { "number": "5511999999999", "presence": "recording", "delay": 60000 } ``` ### Cancelar presença atual: ```json { "number": "5511999999999", "presence": "paused" } ``` ### Usar limite máximo (5 minutos): ```json { "number": "5511999999999", "presence": "composing" } ``` # Enviar status (stories) Source: https://docs.wppfy.com/pt-br/api-reference/send-message/send-status-stories /openapi-pt-BR.json post /send/status Envia um status do WhatsApp com suporte para texto, imagem, vídeo e áudio. Este endpoint possui 4 modos de uso: - envio normal: omita `recipients`, `max_recipients` e `group` - envio explícito: informe `recipients` para enviar apenas para números específicos; a API aproveita os válidos e descarta os inválidos com motivo no `debug` - envio parcial: informe `max_recipients` para limitar a audiência ou aplicar um cap de segurança sobre `recipients` - status de grupo: informe `group` com o JID do grupo (`@g.us`) ## Observação importante sobre `recipients` Quando `recipients` é informado, a API: - aceita números em formato WhatsApp, JIDs `@s.whatsapp.net` e JIDs `@lid` - quando recebe `@lid`, tenta resolver esse identificador para o PN (`@s.whatsapp.net`) usando os vínculos conhecidos pela instância - se o `@lid` não puder ser resolvido para PN, esse item é descartado com motivo `lid_unresolved` - valida se o destinatário existe no WhatsApp usando o mesmo fluxo de verificação do envio normal, com batch para evitar uma chamada remota por recipient - cruza os destinatários verificados com a audiência permitida pela privacidade do status, aceitando equivalência PN/LID quando esse vínculo é conhecido - recipients descartados aparecem em `debug.discarded_recipients`, com motivos como `invalid_format`, `lid_unresolved`, `not_on_whatsapp`, `outside_status_audience` e `duplicate` - a requisição só retorna `400` quando nenhum recipient válido sobra para envio ## Observação importante sobre `max_recipients` O campo `max_recipients` foi adicionado como mitigação operacional. Já observamos casos em que o WhatsApp bloqueia imediatamente o envio de status quando a audiência é muito grande (por exemplo, agendas com milhares de contatos, como ~3.000). A causa exata ainda não está totalmente clara, então a recomendação é começar com limites menores e aumentar gradualmente. ## Status de grupo Com `group`, o status é publicado no grupo e aparece para os membros na aba Status, no lugar do status da conta. A conta precisa participar do grupo. Vale para texto, imagem e vídeo: áudio (`audio`, `ptt` e `myaudio`) não funciona no status de grupo e retorna `400`. - não combina com `recipients` nem `max_recipients` (retorna `400`) - a resposta traz `Id`, `content`, `messageTimestamp` e `status`, sem `debug` ## Tipos suportados - `text`: texto com cor de fundo e fonte - `image`: imagem com legenda opcional - `video`: vídeo com legenda opcional - `audio`: áudio normal - `myaudio`: áudio enviado como voz - `ptt`: áudio enviado como voz ## Cores de fundo Informe um valor de `1` a `19`. A API converte esse índice para a cor usada pelo WhatsApp. - `1`: amarelo esverdeado suave - `2`: amarelo pálido - `3`: amarelo alaranjado vibrante - `4`: verde vibrante - `5`: verde musgo - `6`: verde claro - `7`: azul piscina - `8`: azul intenso - `9`: azul claro acinzentado - `10`: lilás claro - `11`: lilás quente - `12`: roxo azulado - `13`: magenta profundo - `14`: rosa suave - `15`: salmão rosado - `16`: marrom claro - `17`: cinza claro azulado - `18`: cinza médio - `19`: cinza profundo padrão Exemplo rápido: - `7`: azul piscina - `13`: magenta profundo - `19`: cinza profundo (padrão) ## Fontes válidas para `type=text` Valores aceitos atualmente: `0`, `1`, `2`, `6`, `7`, `8`, `9`, `10`. ## Limites - `text`: máximo de 656 caracteres - `max_recipients`: não pode ser negativo - `recipients`: aceita números, JIDs `@s.whatsapp.net` e JIDs `@lid` - `@lid` só entra no envio quando puder ser resolvido localmente para um PN válido; caso contrário, é descartado - para tipos de mídia, `file` é obrigatório - `group`: JID do grupo (`@g.us`) Exemplo de envio explícito: ```json { "type": "text", "text": "Novidades chegando!", "recipients": [ "5511999999999", "5511888888888@s.whatsapp.net" ] } ``` Exemplo de envio parcial: ```json { "type": "text", "text": "Novidades chegando!", "background_color": 7, "font": 1, "max_recipients": 100 } ``` Exemplo de status de grupo: ```json { "type": "image", "file": "https://exemplo.com/status.jpg", "text": "Aviso para o grupo", "group": "120363123456789012@g.us" } ``` # Enviar mensagem de texto Source: https://docs.wppfy.com/pt-br/api-reference/send-message/send-text-message /openapi-pt-BR.json post /send/text Envia uma mensagem de texto para um contato, grupo ou canal/newsletter. ## Recursos Específicos - **Preview de links** com suporte a personalização automática ou customizada - **Formatação básica** do texto - **Substituição automática de placeholders** dinâmicos ## Envio para Newsletter Para enviar texto para um canal, use o mesmo campo `number`, mas informe o JID completo do canal: - Exemplo: `120363123456789012@newsletter` ```json { "number": "120363123456789012@newsletter", "text": "Post publicado no canal" } ``` ## Responder enquete, lista ou botão Use este mesmo endpoint para responder uma mensagem interativa que esteja salva no histórico local da instância. Envie: - `number`: chat onde a mensagem original foi recebida ou enviada; - `replyid`: ID da mensagem interativa original; - `text`: seleção iniciada por `>`. O marcador `>` é obrigatório para gerar uma resposta interativa. Sem ele, a API envia apenas uma mensagem de texto citando a original. ### Responder uma enquete Use a posição da opção, começando em 1. Nesta documentação pública, responda somente uma opção por requisição. ```json { "number": "5511999999999", "replyid": "3EB0ID_DA_ENQUETE", "text": ">1" } ``` ### Responder uma lista Prefira o `rowId` configurado ao criar a lista. Também são aceitos o texto exato do item ou sua posição (`>1`). ```json { "number": "5511999999999", "replyid": "3EB0ID_DA_LISTA", "text": ">plano_pro" } ``` ### Responder um botão Prefira o ID do botão de resposta rápida. Também são aceitos o texto exato exibido ou sua posição (`>1`). Isso vale para botões rápidos legados, templates, native flow e carrossel. Botões de URL, ligação ou cópia executam a própria ação e não são respondidos por este fluxo. ```json { "number": "5511999999999", "replyid": "3EB0ID_DOS_BOTOES", "text": ">confirmar" } ``` A API devolve erro quando a mensagem original não está disponível ou a opção informada não existe. ## Campos Comuns Este endpoint suporta todos os **campos opcionais comuns** documentados na tag **"Enviar Mensagem"**, incluindo: `delay`, `readchat`, `readmessages`, `replyid`, `mentions`, `forward`, `track_source`, `track_id`, placeholders e envio para grupos. ## Preview de Links ### Preview Automático ```json { "number": "5511999999999", "text": "Confira: https://exemplo.com", "linkPreview": true } ``` ### Preview Personalizado ```json { "number": "5511999999999", "text": "Confira nosso site! https://exemplo.com", "linkPreview": true, "linkPreviewTitle": "Título Personalizado", "linkPreviewDescription": "Uma descrição personalizada do link", "linkPreviewImage": "https://exemplo.com/imagem.jpg", "linkPreviewLarge": true } ``` # Atualizar pagamento e pedido Source: https://docs.wppfy.com/pt-br/api-reference/send-message/update-payment-and-order /openapi-pt-BR.json post /message/payment/status Envia ao cliente uma atualização de um pedido originado por `POST /send/request-payment`. No campo `id`, envie o `id` ou o `messageid` retornado pela solicitação. `paid` é opcional: quando omitido, somente o estado do pedido é enviado. `note` aparece na atualização do pedido. # Server-Sent Events (SSE) Source: https://docs.wppfy.com/pt-br/api-reference/server-sent-events-sse/server-sent-events-sse /openapi-pt-BR.json get /sse Receber eventos em tempo real via Server-Sent Events (SSE) ### Funcionalidades principais: - conexão HTTP persistente em `text/event-stream` - seleção granular de tipos de eventos - filtragem de tipos de mensagens - autenticação por token na query, compatível com `EventSource` **Eventos Disponíveis**: - `connection`: Alterações no estado da conexão - `history`: Recebimento de histórico de mensagens - `messages`: Novas mensagens recebidas - `messages_update`: Atualizações em mensagens existentes - `call`: Eventos de chamadas VoIP - `contacts`: Atualizações na agenda de contatos - `presence`: Alterações no status de presença - `groups`: Modificações em grupos - `labels`: Gerenciamento de etiquetas - `chats`: Eventos de conversas - `chat_labels`: Alterações em etiquetas de conversas Estabelece uma conexão persistente para receber eventos em tempo real. Este endpoint: 1. Requer autenticação via token 2. Mantém uma conexão HTTP aberta com o cliente 3. Envia eventos conforme ocorrem no servidor 4. Suporta diferentes tipos de eventos Exemplo de uso: ```javascript const eventSource = new EventSource('/sse?token=SEU_TOKEN&events=chats,messages'); eventSource.onmessage = function(event) { const data = JSON.parse(event.data); console.log('Novo evento:', data); }; eventSource.onerror = function(error) { console.error('Erro na conexão SSE:', error); }; ``` Estrutura de um evento: ```json { "type": "message", "data": { "id": "3EB0538DA65A59F6D8A251", "from": "5511999999999@s.whatsapp.net", "to": "5511888888888@s.whatsapp.net", "text": "Olá!", "timestamp": 1672531200000 } } ``` # Criar coleção no catálogo Source: https://docs.wppfy.com/pt-br/api-reference/business/create-catalog-collection /openapi-pt-BR.json post /business/catalog/collection/create Cria uma coleção no catálogo da instância autenticada com produtos existentes. Use os IDs retornados pela listagem de produtos. # Criar ou editar um produto do catálogo Source: https://docs.wppfy.com/pt-br/api-reference/business/create-or-edit-a-catalog-product /openapi-pt-BR.json post /business/catalog/save Cria um produto quando `id` não é informado ou atualiza o produto indicado. Os preços são strings de inteiros em milésimos da moeda (por exemplo, `19990` = R$ 19,99). `currency` é obrigatória quando há `price`, e `currency` ou `sale_price` sem `price` retornam 400. Envie `image_data` em base64 ou Data URL, ou uma `image_url` pública HTTPS para uma imagem nova. Para manter imagens já cadastradas, envie suas URLs em `image_urls`. Uma dessas três fontes de imagem é obrigatória. A edição substitui o produto inteiro: o que não for enviado fica vazio. Para alterar só um campo, leia o produto em `/business/catalog/info` e reenvie os demais: `description`, `price`, `currency`, `sale_price`, `url`, `retailer_id`, `image_urls`, `video_urls`, `compliance_category` e `compliance_info`. Na leitura, a promoção vem em `sale_price.price`; no envio, `sale_price` é só a string do valor. Só `is_hidden` mantém o valor atual quando omitido. # Deletar um produto do catálogo Source: https://docs.wppfy.com/pt-br/api-reference/business/delete-a-catalog-product /openapi-pt-BR.json post /business/catalog/delete Exclui um produto do catálogo comercial. Para retirá-lo da vitrine sem apagar, prefira a operação de ocultar. # Apagar coleção do catálogo Source: https://docs.wppfy.com/pt-br/api-reference/business/delete-catalog-collection /openapi-pt-BR.json delete /business/catalog/collection/{id} Apaga uma coleção da instância autenticada. Os produtos não são apagados do catálogo. # Editar coleção do catálogo Source: https://docs.wppfy.com/pt-br/api-reference/business/edit-catalog-collection /openapi-pt-BR.json patch /business/catalog/collection/{id} Altera apenas os campos enviados da coleção indicada pelo `id` da URL. Envie pelo menos uma alteração. `add_product_ids` adiciona produtos e `remove_product_ids` remove produtos da coleção sem apagá-los do catálogo. # Obter as categorias de negócios Source: https://docs.wppfy.com/pt-br/api-reference/business/get-business-categories /openapi-pt-BR.json get /business/get/categories Lista as categorias aceitas pelo perfil comercial. Use os identificadores retornados ao atualizar a categoria da empresa. # Obter informações de um produto do catálogo Source: https://docs.wppfy.com/pt-br/api-reference/business/get-information-about-a-catalog-product /openapi-pt-BR.json post /business/catalog/info Retorna os detalhes disponíveis de um produto do catálogo. Use o ID obtido na listagem de produtos para abrir ou revisar um item. # Obter o perfil comercial Source: https://docs.wppfy.com/pt-br/api-reference/business/get-the-business-profile /openapi-pt-BR.json post /business/get/profile Retorna os dados públicos do perfil comercial da conta conectada. Use para revisar descrição, endereço, categoria e meios de contato antes de atualizar. # Ocultar um produto do catálogo Source: https://docs.wppfy.com/pt-br/api-reference/business/hide-a-product-from-the-catalog /openapi-pt-BR.json post /business/catalog/hide Retira temporariamente um produto da vitrine sem apagá-lo. O item pode ser exibido novamente pela operação correspondente. # Listar coleções do catálogo Source: https://docs.wppfy.com/pt-br/api-reference/business/list-catalog-collections /openapi-pt-BR.json get /business/catalog/collection/list Lista as coleções do catálogo da instância autenticada. Para a primeira página, não informe `after`. Se a resposta trouxer `response.next`, copie o valor para `after` na próxima chamada. O cursor é opaco. Sem `response.next`, não há mais páginas. # Listar os produtos do catálogo Source: https://docs.wppfy.com/pt-br/api-reference/business/list-catalog-products /openapi-pt-BR.json post /business/catalog/list Lista uma página de produtos do catálogo de um perfil comercial no WhatsApp. Observações: - envie apenas `jid` para buscar a primeira página - a paginação pública usa o campo `after` - copie exatamente o valor retornado em `response.next` e envie na próxima chamada - sem `response.next` na resposta, não há mais páginas - o valor de `after` é um token opaco: não tente decodificar ou modificar - a integração atual retorna até 50 produtos por chamada - a resposta usa exclusivamente o formato atual documentado abaixo # Mostrar um produto do catálogo Source: https://docs.wppfy.com/pt-br/api-reference/business/show-a-catalog-product /openapi-pt-BR.json post /business/catalog/show Torna um produto existente visível no catálogo comercial depois de revisar suas informações e disponibilidade. # Atualizar o perfil comercial Source: https://docs.wppfy.com/pt-br/api-reference/business/update-the-business-profile /openapi-pt-BR.json post /business/update/profile Atualiza os dados do perfil comercial da conta do WhatsApp Business atualmente conectada. Todos os campos são opcionais; apenas os enviados serão atualizados. # Rejeitar chamada recebida Source: https://docs.wppfy.com/pt-br/api-reference/calls/reject-incoming-call /openapi-pt-BR.json post /call/reject Rejeita uma chamada recebida do WhatsApp. O body pode ser enviado vazio `{}`. Os campos `number` e `id` são opcionais e podem ser usados para especificar uma chamada específica. Exemplo de requisição (recomendado): ```json {} ``` Exemplo de requisição com campos opcionais: ```json { "number": "5511999999999", "id": "ABEiGmo8oqkAcAKrBYQAAAAA_1" } ``` Exemplo de resposta: ```json { "response": "Call rejected" } ``` Erros comuns: - 401: Token inválido ou expirado - 400: Número inválido - 500: Erro ao rejeitar chamada # Iniciar chamada de voz Source: https://docs.wppfy.com/pt-br/api-reference/calls/start-voice-call /openapi-pt-BR.json post /call/make Inicia uma chamada de voz para um contato específico. Este endpoint permite: 1. Iniciar chamadas de voz para contatos 2. Funciona apenas com números válidos do WhatsApp 3. O contato receberá uma chamada de voz Sem `fileUrl`, o endpoint apenas faz o telefone do contato tocar e não estabelece uma comunicação de voz bidirecional. Com `fileUrl`, a API reproduz o arquivo quando a chamada é atendida e encerra a ligação ao final do áudio. São aceitos MP3, WAV e OGG/Opus por URL HTTP(S), data URI ou base64, com limite de 25 MB. **Opcional**: Use `call_duration` para definir por quantos segundos a chamada deve tocar. Após esse período a chamada é encerrada automaticamente, sem precisar chamar `/call/reject`. Use `0` para não limitar a reprodução do áudio por tempo. Exemplo de requisição: ```json { "number": "5511999999999", "call_duration": 0, "fileUrl": "https://exemplo.com/audio.mp3" } ``` Exemplo de resposta: ```json { "response": "Call request accepted locally, awaiting WhatsApp confirmation", "confirmed": false, "audio": { "requested": true, "playback": "starts_when_call_is_ready" } } ``` Erros comuns: - 401: Token inválido ou expirado - 400: Número inválido ou ausente - 500: Erro ao iniciar chamada # Arquivar/desarquivar chat Source: https://docs.wppfy.com/pt-br/api-reference/chats/archive-unarchive-chat /openapi-pt-BR.json post /chat/archive Altera o estado de arquivamento de um chat do WhatsApp. - Quando arquivado, o chat é movido para a seção de arquivados no WhatsApp - A ação é sincronizada entre todos os dispositivos conectados - Não afeta as mensagens ou o conteúdo do chat # Configurar mensagens temporárias em chat privado Source: https://docs.wppfy.com/pt-br/api-reference/chats/configure-disappearing-messages-in-a-private-chat /openapi-pt-BR.json post /chat/ephemeral Define o temporizador de mensagens temporárias (disappearing messages) de um chat privado. Valores aceitos para a duração: - `0` ou `off` para desativar - `1d` - `7d` - `90d` Observações: - este endpoint é apenas para chats privados - se o identificador informado for de grupo, a API retorna erro orientando usar `/group/ephemeral` - a resposta inclui o chat com `wa_ephemeralExpiration` atualizado # Deleta chat Source: https://docs.wppfy.com/pt-br/api-reference/chats/deletes-chat /openapi-pt-BR.json post /chat/delete Remove uma conversa, suas mensagens locais ou ambas, conforme as opções enviadas. Você pode escolher: - Deletar o chat do WhatsApp - Limpar a conversa no WhatsApp - Remover o chat do histórico da instância - Remover apenas as mensagens locais do chat - Qualquer combinação das opções acima Observação: - Se clearChatWhatsApp e deleteChatWhatsApp forem true, o clear tem prioridade. # Editar notas internas do chat Source: https://docs.wppfy.com/pt-br/api-reference/chats/edit-chat-internal-notes /openapi-pt-BR.json post /chat/notes/edit Atualiza `wa_notes` de um chat via app state do WhatsApp e persiste o resultado localmente. Regras: - envie `number` - envie `notes` como campo principal - envie string vazia para limpar a nota do chat # Consultar avatar de um chat Source: https://docs.wppfy.com/pt-br/api-reference/chats/get-a-chat-s-avatar /openapi-pt-BR.json post /chat/avatar Retorna a URL temporária da imagem de uma conversa individual ou grupo. Use `preview=true` para solicitar a imagem reduzida ou `preview=false` para solicitar a imagem completa. Quando não houver imagem disponível, a resposta continua válida e retorna `url` vazio. `force=true` solicita uma atualização antecipada, respeitando um intervalo mínimo de 20 segundos por imagem e instância; não use essa opção em polling contínuo. # Consultar contadores de chats Source: https://docs.wppfy.com/pt-br/api-reference/chats/get-chat-counters /openapi-pt-BR.json get /chat/totalcount Retorna contadores totais e não lidos por estado, etiqueta e atendente. Os arrays são retornados vazios quando ainda não há etiquetas ou atendentes. # Consultar notas internas do chat Source: https://docs.wppfy.com/pt-br/api-reference/chats/get-the-chat-s-internal-notes /openapi-pt-BR.json post /chat/notes Retorna `wa_notes` de um chat usando apenas os dados já persistidos localmente. Casos de uso: - ler a anotação local já persistida no chat - consultar notas mesmo durante reconexão da sessão do WhatsApp Regras: - envie `number` - para recarregar do WhatsApp, use `/chat/notes/refresh` # Marcar chat como lido/não lido Source: https://docs.wppfy.com/pt-br/api-reference/chats/mark-chat-as-read-unread /openapi-pt-BR.json post /chat/read Atualiza o status de leitura de um chat no WhatsApp. Quando um chat é marcado como lido: - O contador de mensagens não lidas é zerado - O indicador visual de mensagens não lidas é removido - O remetente recebe confirmação de leitura (se ativado) Quando marcado como não lido: - O chat aparece como pendente de leitura - Não afeta as confirmações de leitura já enviadas # Silenciar chat Source: https://docs.wppfy.com/pt-br/api-reference/chats/mute-chat /openapi-pt-BR.json post /chat/mute Silencia notificações de um chat por um período específico. As opções de silenciamento são: * 0 - Remove o silenciamento * 8 - Silencia por 8 horas * 168 - Silencia por 1 semana (168 horas) * -1 - Silencia permanentemente # Fixar/desafixar chat Source: https://docs.wppfy.com/pt-br/api-reference/chats/pin-unpin-chat /openapi-pt-BR.json post /chat/pin Fixa ou desafixa um chat no topo da lista de conversas. Chats fixados permanecem no topo mesmo quando novas mensagens são recebidas em outros chats. # Recarregar notas internas do chat no WhatsApp Source: https://docs.wppfy.com/pt-br/api-reference/chats/reload-the-chat-s-internal-notes-in-whatsapp /openapi-pt-BR.json post /chat/notes/refresh Faz uma nova leitura das notas internas do chat no WhatsApp antes de retornar o valor atualizado. Uso recomendado: - tente primeiro com `force=false` - se isso não atualizar a nota corretamente, tente `force=true` - use `force=true` apenas como tentativa de correção, porque ele faz uma recarga mais pesada # Busca chats com filtros Source: https://docs.wppfy.com/pt-br/api-reference/chats/search-chats-with-filters /openapi-pt-BR.json post /chat/find 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 }. # Obter configuração do Chatwoot Source: https://docs.wppfy.com/pt-br/api-reference/chatwoot-integration/get-chatwoot-configuration /openapi-pt-BR.json get /chatwoot/config Retorna a configuração atual da integração com Chatwoot para a instância. ### Funcionalidades: - Retorna todas as configurações do Chatwoot incluindo credenciais - Mostra status de habilitação da integração - Útil para verificar configurações atuais antes de fazer alterações # Atualizar configuração do Chatwoot Source: https://docs.wppfy.com/pt-br/api-reference/chatwoot-integration/update-chatwoot-configuration /openapi-pt-BR.json put /chatwoot/config Atualiza a configuração da integração com Chatwoot para a instância. ### Funcionalidades: - Configura todos os parâmetros da integração Chatwoot - Reinicializa automaticamente o cliente Chatwoot quando habilitado - Retorna URL do webhook para configurar no Chatwoot - Sincronização bidirecional de mensagens novas entre WhatsApp e Chatwoot - Sincronização automática de contatos (nome e telefone) - Atualização automática LID → PN (Local ID para Phone Number) - Sistema de nomes inteligentes com til (~) ### Configuração no Chatwoot: 1. Após configurar via API, use a URL retornada no webhook settings da inbox no Chatwoot 2. Configure como webhook URL na sua inbox do Chatwoot 3. A integração ficará ativa e sincronizará mensagens e contatos automaticamente ### 🏷️ Sistema de Nomes Inteligentes: - **Nomes com til (~)**: São atualizados automaticamente quando o contato modifica seu nome no WhatsApp - **Nomes específicos**: Para definir um nome fixo, remova o til (~) do nome no Chatwoot - **Exemplo**: "~João Silva" será atualizado automaticamente, "João Silva" (sem til) permanecerá fixo - **Atualização LID→PN**: Contatos migram automaticamente de Local ID para Phone Number quando disponível - **Sem duplicação**: Durante a migração LID→PN, não haverá duplicação de conversas - **Respostas nativas**: Todas as respostas dos agentes aparecem nativamente no Chatwoot ### 🚧 AVISO IMPORTANTE - INTEGRAÇÃO BETA: - **Fase Beta**: Esta integração está em fase de desenvolvimento e testes - **Uso por conta e risco**: O usuário assume total responsabilidade pelo uso - **Recomendação**: Teste em ambiente não-produtivo antes de usar em produção - **Suporte limitado**: Funcionalidades podem mudar sem aviso prévio ### ⚠️ Limitações Conhecidas: - **Sincronização de histórico**: Não implementada - apenas mensagens novas são sincronizadas # Adiciona um contato à agenda Source: https://docs.wppfy.com/pt-br/api-reference/contacts/adds-a-contact-to-the-address-book /openapi-pt-BR.json post /contact/add Adiciona um novo contato à agenda do celular. O endpoint realiza: - Adiciona o contato à agenda usando o WhatsApp - Usa o campo 'name' tanto para o nome completo quanto para o primeiro nome - Salva as informações do contato na agenda do WhatsApp - Retorna informações do contato adicionado # Verificar Números no WhatsApp Source: https://docs.wppfy.com/pt-br/api-reference/contacts/check-numbers-on-whatsapp /openapi-pt-BR.json post /chat/check Verifica se números fornecidos estão registrados no WhatsApp e retorna informações detalhadas. ### Funcionalidades: - Verifica múltiplos números simultaneamente - Suporta números individuais e IDs de grupo - Retorna nome verificado quando disponível - Identifica grupos e comunidades - Verifica subgrupos de comunidades **Comportamento específico**: - Para números individuais: - Verifica registro no WhatsApp - Retorna nome verificado se disponível - Normaliza formato do número - Para grupos: - Verifica existência - Retorna nome do grupo - Retorna id do grupo de anúncios se buscado por id de comunidade # Consultar detalhes de um chat Source: https://docs.wppfy.com/pt-br/api-reference/contacts/get-chat-details /openapi-pt-BR.json post /chat/details Retorna os dados disponíveis para apresentar ou editar uma conversa: identificação, nomes conhecidos, telefone, foto, estado do chat, dados de lead e informações de grupo quando aplicáveis. Use depois de escolher um chat em `POST /chat/find`. Para obter somente a imagem, prefira `POST /chat/avatar`, mais leve, principalmente em listas com muitos chats. O campo `preview` permite escolher uma imagem menor para interfaces de listagem ou a imagem completa. Cada instância processa até 4 consultas desta rota ao mesmo tempo. A seguinte espera até 2 segundos por uma vaga; se não houver, recebe `429` com o header `Retry-After`. A rota também conta no limite de chamadas da instância. Para contatos individuais, `is_business` indica se há um nome comercial conhecido. `business_name` traz esse nome quando disponível. # Listar todos os contatos com paginacao Source: https://docs.wppfy.com/pt-br/api-reference/contacts/list-all-contacts-with-pagination /openapi-pt-BR.json post /contacts/list Retorna uma lista paginada de contatos da conta do WhatsApp atualmente conectada. Use este endpoint (POST) para controlar `limit` e `offset` via corpo da requisicao. O campo `contactScope` permite escolher entre contatos da agenda, fora da agenda ou todos os contatos conhecidos. A rota GET `/contacts` continua disponivel para quem prefere a lista completa sem paginacao. # Remove um contato da agenda Source: https://docs.wppfy.com/pt-br/api-reference/contacts/removes-a-contact-from-the-address-book /openapi-pt-BR.json post /contact/remove Remove um contato da agenda do celular. O endpoint realiza: - Remove o contato da agenda usando o WhatsApp AppState - Atualiza a lista de contatos sincronizada - Retorna confirmação da remoção # Retorna lista de contatos do WhatsApp Source: https://docs.wppfy.com/pt-br/api-reference/contacts/returns-the-list-of-whatsapp-contacts /openapi-pt-BR.json get /contacts Retorna a lista de contatos do WhatsApp conforme o filtro informado em `contactScope`. O endpoint realiza: - Busca todos os contatos armazenados - Filtra para contatos da agenda, fora da agenda ou todos - Usa `address_book` como padrao quando `contactScope` nao for informado - Retorna dados formatados incluindo JID e informações de nome # Criar resposta rápida Source: https://docs.wppfy.com/pt-br/api-reference/quick-replies/create-quick-reply /openapi-pt-BR.json post /quick-replies Guarda uma mensagem pronta de qualquer tipo: texto, arquivo, contato, localização, menu ou PIX, para usar no atendimento. A mensagem usa o mesmo corpo do envio correspondente; veja a tabela em `message`. # Apagar resposta rápida Source: https://docs.wppfy.com/pt-br/api-reference/quick-replies/delete-quick-reply /openapi-pt-BR.json delete /quick-replies/{id} Apaga a resposta rápida e o arquivo guardado, se houver. Respostas no WhatsApp Business são apagadas lá também. # Editar resposta rápida Source: https://docs.wppfy.com/pt-br/api-reference/quick-replies/edit-quick-reply /openapi-pt-BR.json patch /quick-replies/{id} Altera só os campos enviados. `message` substitui a mensagem inteira; trocar ou remover um arquivo apaga o anterior. Se outra edição trocar a mensagem ao mesmo tempo, esta volta `409` com `conflict` e nada é gravado. Respostas no WhatsApp Business continuam só de texto. # Listar respostas rápidas Source: https://docs.wppfy.com/pt-br/api-reference/quick-replies/list-quick-replies /openapi-pt-BR.json get /quick-replies Lista as respostas rápidas da instância, de qualquer tipo, por ordem de atalho. # Ver resposta rápida Source: https://docs.wppfy.com/pt-br/api-reference/quick-replies/view-quick-reply /openapi-pt-BR.json get /quick-replies/{id} Devolve a resposta rápida pelo `id`.