curl --request POST \
  --url https://api.wppfy.com/send/status \
  --header 'Content-Type: application/json' \
  --header 'token: <api-key>' \
  --data '
{
  "type": "text",
  "text": "Novidades chegando!"
}
'

{
  "Id": "ABCD1234",
  "content": {},
  "messageTimestamp": 1672531200000,
  "status": "Pending",
  "debug": {
    "status_privacy_type": "contacts",
    "audience_recipient_count": 245,
    "total_contacts_in_store": 300,
    "contacts_with_full_name": 245,
    "contacts_with_push_name_only": 32,
    "contacts_with_business_name_only": 23,
    "used_default_privacy_fallback": false,
    "privacy_lookup_error": "privacy unavailable",
    "explicit_recipients": true,
    "requested_recipient_count": 25,
    "resolved_recipient_count": 20,
    "discarded_recipient_count": 5,
    "discarded_recipients": [
      {
        "input": "144637553594388@lid",
        "reason": "lid_unresolved"
      }
    ],
    "max_recipients": 100,
    "selected_recipient_count": 100,
    "partial_send": true
  }
}

{
  "error": "Invalid font",
  "debug": {}
}

{
  "error": "failed to determine status audience: privacy unavailable"
}

Enviar Mensagem

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:

{
  "type": "text",
  "text": "Novidades chegando!",
  "recipients": [
    "5511999999999",
    "5511888888888@s.whatsapp.net"
  ]
}

Exemplo de envio parcial:

{
  "type": "text",
  "text": "Novidades chegando!",
  "background_color": 7,
  "font": 1,
  "max_recipients": 100
}

Exemplo de status de grupo:

{
  "type": "image",
  "file": "https://exemplo.com/status.jpg",
  "text": "Aviso para o grupo",
  "group": "120363123456789012@g.us"
}

POST

send

status

curl --request POST \
  --url https://api.wppfy.com/send/status \
  --header 'Content-Type: application/json' \
  --header 'token: <api-key>' \
  --data '
{
  "type": "text",
  "text": "Novidades chegando!"
}
'

{
  "Id": "ABCD1234",
  "content": {},
  "messageTimestamp": 1672531200000,
  "status": "Pending",
  "debug": {
    "status_privacy_type": "contacts",
    "audience_recipient_count": 245,
    "total_contacts_in_store": 300,
    "contacts_with_full_name": 245,
    "contacts_with_push_name_only": 32,
    "contacts_with_business_name_only": 23,
    "used_default_privacy_fallback": false,
    "privacy_lookup_error": "privacy unavailable",
    "explicit_recipients": true,
    "requested_recipient_count": 25,
    "resolved_recipient_count": 20,
    "discarded_recipient_count": 5,
    "discarded_recipients": [
      {
        "input": "144637553594388@lid",
        "reason": "lid_unresolved"
      }
    ],
    "max_recipients": 100,
    "selected_recipient_count": 100,
    "partial_send": true
  }
}

{
  "error": "Invalid font",
  "debug": {}
}

{
  "error": "failed to determine status audience: privacy unavailable"
}

Autorizações

token

string

header

obrigatório

Corpo

application/json

type

enum<string>

obrigatório

Tipo do status.

Opções disponíveis:

text,

image,

video,

audio,

myaudio,

ptt

Exemplo:

"text"

text

string

Texto principal ou legenda.

Exemplo:

"Novidades chegando!"

background_color

integer

Índice da cor de fundo para status em texto.

Intervalo obrigatório: 1 <= x <= 19

Exemplo:

7

font

enum<integer>

Fonte aceita para type=text.

Opções disponíveis:

0,

1,

2,

6,

7,

8,

9,

10

Exemplo:

1

file

string

URL ou base64 do arquivo de mídia.

Exemplo:

"https://example.com/video.mp4"

thumbnail

string

Campo aceito no payload; a API gera a miniatura automaticamente quando necessário.

Exemplo:

"https://example.com/thumb.jpg"

mimetype

string

MIME type do arquivo, quando necessário.

Exemplo:

"video/mp4"

recipients

string[]

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.

Exemplo:

[
  "5511999999999",
  "5511888888888@s.whatsapp.net"
]

max_recipients

integer

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.

Intervalo obrigatório: x >= 0

Exemplo:

100

group

string

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.

Exemplo:

"120363123456789012@g.us"

Resposta

Status enviado com sucesso

string

ID da mensagem quando há envio real.

Exemplo:

"ABCD1234"

content

object

Conteúdo processado da mensagem quando há envio real.

messageTimestamp

integer

Timestamp em milissegundos quando há envio real.

Exemplo:

1672531200000

status

string

Status do envio quando há envio real.

Exemplo:

"Pending"

debug

object

Métricas agregadas da audiência e da seleção aplicada.

Show child attributes

Instancia

CRM

Proxy

Perfil

Enviar Mensagem

Mensagem Async

Ações na mensagem e Buscar

Grupos e Comunidades

Newsletters e Canais

Server-Sent Events (SSE)

Bloqueios

Etiquetas

Chats

Contatos

Chamadas

Integração Chatwoot

Business

Respostas Rápidas

Enviar status (stories)

Observação importante sobre `recipients`

Observação importante sobre `max_recipients`

Status de grupo

Tipos suportados

Cores de fundo

Fontes válidas para `type=text`

Limites

Autorizações

Corpo

Resposta