> ## Documentation Index > Fetch the complete documentation index at: https://docs.wppfy.com/llms.txt > Use this file to discover all available pages before exploring further. # Enviar status (stories) > 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" } ``` ## OpenAPI ````yaml /openapi-pt-BR.json post /send/status openapi: 3.1.0 info: title: WppFy - WhatsApp API version: 1.0.0 description: > API para gerenciamento de instâncias do WhatsApp e comunicações. ## Recomendação Importante: WhatsApp Business **É ALTAMENTE RECOMENDADO usar contas do WhatsApp Business** em vez do WhatsApp normal para integração, o WhatsApp normal pode apresentar inconsistências, desconexões, limitações e instabilidades durante o uso com a nossa API. ## Autenticação - Endpoints regulares requerem um header 'token' com o token da instância ## Estados da Instância As instâncias podem estar nos seguintes estados: - `disconnected`: Desconectado do WhatsApp - `connecting`: Em processo de conexão - `connected`: Conectado e autenticado com sucesso servers: - url: https://api.wppfy.com security: - token: [] tags: - name: Instancia description: | Operações relacionadas ao ciclo de vida de uma instância, como conectar, desconectar e verificar o status. - name: Proxy description: > A WppFy opera com um proxy interno como padrão. Você pode manter esse padrão, configurar um proxy próprio via `proxy_url` ou usar seu celular android como proxy instalando o app em https://github.com/WppFy/silver_proxy_apk (APK direto: https://github.com/WppFy/silver_proxy_apk/raw/refs/heads/main/silver_proxy.apk). Se nada for enviado, seguimos no proxy interno. IPs são brasileiros; para clientes internacionais, considere um proxy da região do cliente. - name: Perfil description: | Operações relacionadas ao perfil da instância do WhatsApp, como alterar nome e imagem de perfil. - name: Business description: | ⚠️ **EXPERIMENTAL** - Endpoints ainda não testados completamente. Operações relacionadas ao perfil comercial do WhatsApp Business. Permite consultar e atualizar dados do perfil comercial como descrição, endereço, email, categorias e gerenciar o catálogo de produtos. **Requisitos:** - A conta atualmente conectada deve ser uma conta **WhatsApp Business** - Contas pessoais do WhatsApp não possuem perfil comercial **Nota:** Estes endpoints podem não funcionar como esperado. Reporte problemas encontrados. - name: Chamadas description: | Operações relacionadas a chamadas peloWhatsApp. Permite realizar e rejeitar chamadas programaticamente. - name: Enviar Mensagem description: > Endpoints para envio de mensagens do WhatsApp com diferentes tipos de conteúdo. ## Campos Opcionais Comuns Todos os endpoints de envio de mensagem suportam os seguintes campos opcionais: - **`delay`** *(integer)*: Atraso em milissegundos antes do envio - Durante o atraso aparecerá "Digitando..." ou "Gravando áudio..." dependendo do tipo - Exemplo: `5000` (5 segundos) - **`readchat`** *(boolean)*: Marcar chat como lido após envio - Remove o contador de mensagens não lidas do chat - Exemplo: `true` - **`readmessages`** *(boolean)*: Marcar últimas mensagens recebidas como lidas - Marca as últimas 10 mensagens **recebidas** (não enviadas por você) como lidas - Útil para confirmar leitura de mensagens pendentes antes de responder - Diferente do `readchat` que apenas remove contador de não lidas - Exemplo: `true` - **`replyid`** *(string)*: ID da mensagem para responder - Cria uma resposta vinculada à mensagem original - Suporte varia por tipo de mensagem - Exemplo: `"3A12345678901234567890123456789012"` - **`mentions`** *(string)*: Números para mencionar (apenas para envio em grupos) - Números específicos: `"5511999999999,5511888888888"` - Mencionar todos: `"all"` - **`forward`** *(boolean)*: Marca a mensagem como encaminhada no WhatsApp - Adiciona o indicador "Encaminhada" na mensagem - Exemplo: `true` - **`track_source`** *(string)*: Origem do rastreamento da mensagem - Identifica o sistema ou fonte que está enviando a mensagem - Útil para integrações (ex: "chatwoot", "crm", "chatbot") - Exemplo: `"chatwoot"` - **`track_id`** *(string)*: ID para rastreamento da mensagem - Identificador livre para acompanhar a mensagem em sistemas externos - Permite correlacionar mensagens entre diferentes plataformas - **Nota**: O sistema aceita valores duplicados - não há validação de unicidade - Use o mesmo ID em várias mensagens se fizer sentido para sua integração - Exemplo: `"msg_123456789"` ### Envio para Grupos - **`number`** *(string)*: Para enviar mensagem para grupo, use o ID do grupo que termina com `@g.us` - Exemplo: `"120363012345678901@g.us"` - **Como obter o ID do grupo:** - Use o `chatid` do webhook recebido quando alguém envia mensagem no grupo - Use o endpoint `GET /group/list` para listar todos os grupos e seus IDs ## Placeholders Disponíveis Todos os endpoints de envio de mensagem suportam placeholders dinâmicos para personalização automática: ### Campos de Nome - **`{{name}}`**: Nome consolidado do chat, usando a primeira opção disponível: 1. Nome do lead (`lead_name`) 2. Nome completo do lead (`lead_fullName`) 3. Nome do contato no WhatsApp (`wa_contactName`) 4. Nome do perfil do WhatsApp (`wa_name`) - **`{{first_name}}`**: Primeira palavra válida do nome consolidado (mínimo 2 caracteres) ### Campos do WhatsApp - **`{{wa_name}}`**: Nome do perfil do WhatsApp - **`{{wa_contactName}}`**: Nome do contato como salvo no WhatsApp ### Campos do Lead - **`{{lead_name}}`**: Nome do lead - **`{{lead_fullName}}`**: Nome completo do lead - **`{{lead_personalid}}`**: ID pessoal (CPF, CNPJ, etc) - **`{{lead_email}}`**: Email do lead - **`{{lead_status}}`**: Status atual do lead - **`{{lead_notes}}`**: Anotações do lead - **`{{lead_assignedAttendant_id}}`**: ID do atendente designado ### Campos Personalizados Campos adicionados via custom fields são acessíveis usando `{{lead_field01}}` à `{{lead_field20}}` ou usar `{{nomedocampo}}` definido em `/instance/updateFieldsMap`. ### Exemplo de Uso ``` Olá {{name}}! Vi que você trabalha na {{company}}. Seu email {{lead_email}} está correto? ``` **💡 Dica**: Use `/chat/find` para buscar dados do chat e ver os campos disponíveis antes de enviar mensagens com placeholders. - name: Mensagem Async description: > Controles operacionais da fila interna de envio assíncrono usada quando um endpoint de envio recebe `async=true`. Esta seção serve para: - consultar o estado atual da fila async - configurar o delay entre mensagens enviadas com `async=true` - limpar backlog pendente e cancelar mensagens ainda não concluídas Escopo: - cobre apenas a fila interna de mensagens diretas async - não altera mensagens já enviadas com sucesso - name: Ações na mensagem e Buscar - name: Chats - name: Contatos - name: Bloqueios - name: Etiquetas - name: Grupos e Comunidades - name: Newsletters e Canais description: > Operações para leitura e acompanhamento de canais do WhatsApp (newsletters). Casos de uso principais: - listar posts já publicados em um canal - editar posts recentes de um canal - deletar posts recentes de um canal - consultar views e reações dos posts - integrar canais sem necessidade de persistir as mensagens localmente Observações: - `/newsletter/messages` retorna o conteúdo dos posts - `/newsletter/messages/edit` edita o conteúdo de posts recentes - `/newsletter/messages/delete` apaga posts recentes - views (`viewsCount`) e reactions (`reactionCounts`) vêm em cada post de `/newsletter/messages`, não por evento de webhook - `/newsletter/updates` está obsoleta: o WhatsApp não responde e a API devolve 504 - newsletters usam rotas próprias e não devem usar `/message/edit` ou `/message/delete` - name: Respostas Rápidas description: > Gerenciamento de respostas rápidas para agilizar o atendimento. **⚠️ Importante**: Este recurso tem serventia apenas se você utilizar um sistema frontend/interface personalizada para registrar e utilizar as respostas. A API apenas armazena as respostas, mas não as aplica automaticamente. ### Como funciona: - **Criar**: Cadastre respostas pré-definidas com títulos e conteúdo - **Listar**: Recupere todas as respostas cadastradas para exibir na sua interface - **Usar**: Seu sistema frontend pode usar essas respostas para agilizar digitação ### Casos de uso: - Interfaces web personalizadas de atendimento - Apps mobile com sugestões de resposta - Sistemas CRM com templates de mensagem - Ferramentas de produtividade para atendentes **Não é um chatbot**: Para respostas automáticas, use os recursos de Chatbot. - name: CRM description: > Sistema completo de gestão de relacionamento com clientes integrado à API. **💾 Armazenamento interno**: Todos os dados dos leads ficam salvos diretamente na API, eliminando a necessidade de bancos de dados externos. Sua aplicação pode focar apenas na interface e lógica de negócio. ### Recursos disponíveis: - **📋 20+ campos personalizáveis**: Nome, telefone, email, empresa, observações, etc. - **🏷️ Sistema de etiquetas**: Organize e categorize seus contatos - **🔍 Busca avançada**: Filtre por qualquer campo ou etiqueta - **📊 Histórico completo**: Todas as interações ficam registradas automaticamente ### 🎯 Placeholders em mensagens: Use variáveis dinâmicas nas mensagens para personalização automática: ``` Olá {{nome}}! Vi que você trabalha na {{empresa}}. Seu email {{email}} está correto? Observações: {{observacoes}} ``` ### Fluxo típico: 1. **Captura**: Leads chegam via WhatsApp ou formulários 2. **Enriquecimento**: Adicione dados usando `/chat/editLead` 3. **Segmentação**: Organize com etiquetas 4. **Comunicação**: Envie mensagens personalizadas com placeholders 5. **Acompanhamento**: Histórico fica salvo automaticamente **Ideal para**: Vendas, marketing, atendimento, qualificação de leads - name: Integração Chatwoot description: > **🚧 INTEGRAÇÃO BETA - Sistema de integração com Chatwoot para atendimento unificado** **⚠️ AVISO**: Esta integração está em fase BETA. Use por sua conta e risco. Recomendamos testes em ambiente não-produtivo antes do uso em produção. Esta categoria contém recursos para configurar e gerenciar a integração com o Chatwoot, uma plataforma de atendimento ao cliente open-source. A integração permite centralizar conversas do WhatsApp no Chatwoot. ### Recursos disponíveis: - 🔧 **Configuração Completa**: Configure URL, tokens e credenciais do Chatwoot - 📬 **Sincronização Bidirecional**: Mensagens novas entre WhatsApp e Chatwoot são sincronizadas automaticamente - 📱 **Gerenciamento de Contatos**: Sincronização automática de nomes e telefones - 🔄 **Atualização LID→PN**: Migração automática de Local ID para Phone Number - 🏷️ **Nomes Inteligentes**: Sistema de nomes com til (~) para atualização automática - 🚫 **Separação de Grupos**: Opção para ignorar grupos na sincronização - 👤 **Assinatura de Mensagens**: Identificação do agente nas mensagens enviadas - 🔗 **Webhook Automático**: URL gerada automaticamente para configurar no Chatwoot ### 🏷️ Sistema de Nomes Inteligentes: - **Nomes com til (~)**: Atualizados automaticamente quando contato modifica nome no WhatsApp - **Nomes específicos**: Para nome fixo, remover til (~) do nome no Chatwoot - **Exemplo**: "~João Silva" = automático, "João Silva" = fixo - **Migração LID→PN**: Sem duplicação de conversas durante a transição - **Respostas nativas**: Aparecem diretamente no Chatwoot sem marcações externas ### ⚠️ Limitações conhecidas: - **Sincronização de histórico**: Não implementada - apenas mensagens novas são sincronizadas ### Casos de uso: - Atendimento centralizado no Chatwoot - Equipes de suporte com múltiplos agentes - Integração com CRM via Chatwoot - Centralização de canais de comunicação - Gestão automática de contatos e nomes **Ideal para**: Empresas com equipes de atendimento, call centers, suporte técnico (em ambiente de testes) **Requer**: Instância do Chatwoot configurada, tokens de API e ambiente de testes **🚧 Lembre-se**: Integração em BETA - funcionalidades podem mudar sem aviso prévio - name: Server-Sent Events (SSE) paths: /send/status: post: tags: - Enviar Mensagem summary: Enviar status (stories) description: > 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" } ``` requestBody: required: true content: application/json: schema: type: object properties: type: type: string enum: - text - image - video - audio - myaudio - ptt description: Tipo do status. example: text text: type: string description: Texto principal ou legenda. example: Novidades chegando! background_color: type: integer minimum: 1 maximum: 19 description: Índice da cor de fundo para status em texto. example: 7 font: type: integer enum: - 0 - 1 - 2 - 6 - 7 - 8 - 9 - 10 description: Fonte aceita para `type=text`. example: 1 file: type: string description: URL ou base64 do arquivo de mídia. example: https://example.com/video.mp4 thumbnail: type: string description: >- Campo aceito no payload; a API gera a miniatura automaticamente quando necessário. example: https://example.com/thumb.jpg mimetype: type: string description: MIME type do arquivo, quando necessário. example: video/mp4 recipients: type: array description: >- Lista explícita de destinatários. Aceita números em formato WhatsApp, JIDs `@s.whatsapp.net` e JIDs `@lid`. A API valida item a item, descarta os inválidos com motivo no `debug` e envia para o subconjunto válido restante. Entradas `@lid` dependem de resolução conhecida para PN. items: type: string example: - '5511999999999' - 5511888888888@s.whatsapp.net max_recipients: type: integer minimum: 0 description: >- Limita o envio a um subconjunto determinístico da audiência. Quando `recipients` for informado, funciona como cap de segurança sobre a lista explícita já validada. example: 100 group: type: string description: >- JID do grupo (`@g.us`). Publica o status no grupo, para os membros, em vez do status da conta. Não combina com `recipients` nem `max_recipients`. Só texto, imagem e vídeo: áudio retorna `400`. example: 120363123456789012@g.us required: - type examples: text: summary: Status de texto value: type: text text: Novidades chegando! image: summary: Status com imagem value: type: image file: https://exemplo.com/status.jpg text: Confira a novidade audio: summary: Status com áudio value: type: audio file: https://exemplo.com/audio.mp3 group: summary: Status de grupo value: type: image file: https://exemplo.com/status.jpg text: Aviso para o grupo group: 120363123456789012@g.us responses: '200': description: Status enviado com sucesso content: application/json: schema: type: object properties: Id: type: string description: ID da mensagem quando há envio real. example: ABCD1234 content: type: object description: Conteúdo processado da mensagem quando há envio real. messageTimestamp: type: integer description: Timestamp em milissegundos quando há envio real. example: 1672531200000 status: type: string description: Status do envio quando há envio real. example: Pending debug: type: object description: Métricas agregadas da audiência e da seleção aplicada. properties: status_privacy_type: type: string example: contacts audience_recipient_count: type: integer example: 245 total_contacts_in_store: type: integer example: 300 contacts_with_full_name: type: integer example: 245 contacts_with_push_name_only: type: integer example: 32 contacts_with_business_name_only: type: integer example: 23 used_default_privacy_fallback: type: boolean example: false privacy_lookup_error: type: string example: privacy unavailable explicit_recipients: type: boolean example: true requested_recipient_count: type: integer example: 25 resolved_recipient_count: type: integer example: 20 discarded_recipient_count: type: integer example: 5 discarded_recipients: type: array items: type: object properties: input: type: string example: 144637553594388@lid reason: type: string example: lid_unresolved max_recipients: type: integer example: 100 selected_recipient_count: type: integer example: 100 partial_send: type: boolean example: true '400': description: Requisição inválida content: application/json: schema: type: object properties: error: type: string example: Invalid font debug: type: object description: >- Presente especialmente quando `recipients` foi informado, para indicar quais itens foram descartados antes de concluir que nenhum recipient válido sobrou. '401': description: Não autorizado '500': description: Erro interno do servidor content: application/json: schema: type: object properties: error: type: string example: 'failed to determine status audience: privacy unavailable' components: securitySchemes: token: name: token type: apiKey in: header ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.