Enviar status (stories)

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",
    "5511888888888@s.whatsapp.net"
  ]
}

Exemplo de envio parcial:

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