NODAPI

Enviar Mensagem

Enviar status (stories)

POST/send/status
  • Conta no limite de envio da conexão. Ao passar do limite, a resposta é 429.

Autenticação: envie a chave da conexão no header token ou em Authorization: Bearer.

Envia um status do WhatsApp com suporte para texto, imagem, vídeo e áudio.

Este endpoint possui 3 modos de uso:

  • envio normal: omita recipients e max_recipients
  • envio explícito: informe recipients para enviar apenas para números específicos; o backend 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

Observação importante sobre recipients

Quando recipients é informado, o backend:

  • aceita números em formato WhatsApp, JIDs @s.whatsapp.net e JIDs @lid
  • quando recebe @lid, primeiro tenta resolver esse identificador para o PN (@s.whatsapp.net) usando o cache local de LID do WhatsApp
  • 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 atual permitida pela privacidade do status, aceitando equivalência PN/LID quando o cache local conhece esse vínculo
  • 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.

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. O backend converte esse índice para a cor ARGB 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

Exemplo de envio explícito:

{
  "type": "text",
  "text": "Novidades chegando!",
  "recipients": [
    "5511999999999",
    "[email protected]"
  ]
}

Exemplo de envio parcial:

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

Corpo da requisição (JSON)

CampoTipoDescrição
type*string

Tipo do status.

Exemplo: text

textstring

Texto principal ou legenda.

Exemplo: Novidades chegando!

background_colorinteger

Índice da cor de fundo para status em texto.

Exemplo: 7

fontinteger

Fonte aceita para type=text.

Exemplo: 1

filestring

URL ou base64 do arquivo de mídia.

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

thumbnailstring

Campo aceito no payload; o backend gera thumbnail automaticamente quando necessário.

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

mimetypestring

MIME type do arquivo, quando necessário.

Exemplo: video/mp4

recipientsarray<string>

Lista explícita de destinatários. Aceita números em formato WhatsApp, JIDs @s.whatsapp.net e JIDs @lid. O backend 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 local para PN.

Exemplo: 5511999999999,[email protected]

max_recipientsinteger

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.

Exemplo: 100

* obrigatório

Respostas

  • 200Status enviado com sucesso
  • 400Requisição inválida
  • 401Não autorizado
  • 500Erro interno do servidor

Experimente

Atenção: a chamada é real. Ela roda na sua conexão e pode enviar mensagem de verdade. A chave fica só nesta tela e some ao sair dela; nunca é guardada.

Cole a chave gerada no painel.