Pular para o conteúdo principal
POST
/
api
/
message
/
status
/
:instance
Enviar Status
curl --request POST \
  --url https://api.example.com/api/message/status/:instance \
  --header 'Content-Type: <content-type>' \
  --header 'token: <token>' \
  --data '
{
  "type": "<string>",
  "message": "<string>",
  "mediaUrl": "<string>",
  "mimeType": "<string>",
  "fileName": "<string>",
  "backgroundColor": "<string>",
  "font": "<string>",
  "isVoice": true,
  "duration": {},
  "waveform": [
    {}
  ],
  "source": "<string>"
}
'
Auth: TokenAccount ou TokenInstance • Rate-limit: Global (100/min) • Idempotente: não

​
Descrição

Publica um status (story) de 24 horas no perfil da instância. Suporta quatro tipos: text (texto puro com cor de fundo e fonte), image, video e audio. Diferente dos outros endpoints, não há campo number, o status é publicado em status@broadcast e fica visível para todos os contatos que têm permissão (configuração do app). Menções não são suportadas neste endpoint.

​
Exemplos

​
Status de texto com cor e fonte

Publica um status puramente textual com cor de fundo customizada e fonte. Não usa mediaUrl. 
curl -X POST "https://ryzeapi.cloud/api/message/status/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "type":            "text",
    "message":         "Estamos chegando em Maio com novidades!",
    "backgroundColor": "#FF6600",
    "font":            "serif"
  }'

​
Status de imagem

Publica uma imagem como status. mediaUrl é obrigatório para tipos não-texto. message aparece como legenda. 
curl -X POST "https://ryzeapi.cloud/api/message/status/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "type":     "image",
    "message":  "Lançamento da nova versão!",
    "mediaUrl": "https://cdn.example.com/banner-lancamento.jpg"
  }'

​
Status de vídeo

Publica um vídeo curto como status. WhatsApp limita stories de vídeo a 30 segundos, se a mídia for maior, é cortada. 
curl -X POST "https://ryzeapi.cloud/api/message/status/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "type":     "video",
    "message":  "Bastidores da gravação desta semana",
    "mediaUrl": "https://cdn.example.com/teaser.mp4",
    "mimeType": "video/mp4"
  }'

​
Status de áudio (mensagem de voz)

Publica um áudio como status. Por padrão é tratado como PTT (voz). Use isVoice: false para tratar como áudio comum. 
curl -X POST "https://ryzeapi.cloud/api/message/status/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "type":     "audio",
    "message":  "Recado de hoje",
    "mediaUrl": "https://cdn.example.com/recado.ogg",
    "mimeType": "audio/ogg; codecs=opus",
    "isVoice":  true
  }'

​
Resposta de sucesso

O messageType ecoa o type enviado (text, image, video ou audio) e o chat.jid é sempre status@broadcast. O messageId retornado pode ser usado para deletar a publicação antes das 24h via endpoint de apagar mensagem.
200 OK
{
  "success": true,
  "message": "Status sent successfully",
  "status":  "sent",
  "data": {
    "messageId":   "3EB08FCF27E532F1B0F5",
    "direction":   "sent",
    "messageType": "text",
    "content":     "Estamos chegando em Maio com novidades!",
    "source":      "api",
    "timestamp":   "2026-04-30T14:30:00Z",
    "chat": {
      "jid":     "status@broadcast",
      "isGroup": false
    },
    "sender": {
      "jid":      "5511777777777@s.whatsapp.net",
      "instance": "minha-instancia"
    }
  }
}

​
Parâmetros de rota

​
instance
string
obrigatório
Nome da instância (ex.: $Instance_Name).

​
Headers

​
token
string
obrigatório
TokenAccount ou TokenInstance.
​
Content-Type
string
obrigatório
application/json

​
Request body

​
type
string
obrigatório
Tipo do status. Valores aceitos: text, image, video, audio.
​
message
string
obrigatório
Conteúdo textual do status. Para type=text, é o próprio texto exibido. Para mídia (image, video, audio), funciona como legenda.
​
mediaUrl
string
URL pública do arquivo de mídia. Obrigatório quando type é image, video ou audio. Ignorado quando type=text.
​
mimeType
string
MIME type da mídia (ex.: image/jpeg, video/mp4, audio/ogg; codecs=opus). Opcional, auto-detectado quando omitido.
​
fileName
string
Nome do arquivo. Opcional, raramente relevante para stories.
​
backgroundColor
string
Apenas para type=text. Cor de fundo do status em hex (ex.: #FF0000, #00AAFF). Quando omitido, o WhatsApp usa a cor padrão do tema.
​
font
string
Apenas para type=text. Fonte do texto. Valores comuns: system, serif, sans-serif.
​
isVoice
boolean
padrão:"true"
Apenas para type=audio. Quando true (padrão), o áudio é publicado como PTT (mensagem de voz). Quando false, vira áudio comum com player normal.
​
duration
uint32
Apenas para type=audio. Duração em segundos. Opcional, auto-detectado pela ferramenta de transcodificação.
​
waveform
byte[]
Apenas para type=audio. Forma de onda customizada (array de bytes). Opcional, auto-gerada se omitida.
​
source
string
padrão:"api"
Identificador de origem para rastreabilidade (ex.: crm, bot-marketing, n8n).

​
Notas

  • Não há campo number, stories vão sempre para status@broadcast e ficam visíveis pelas regras de privacidade configuradas no app (Configurações → Privacidade → Status).
  • Menções não são suportadas neste endpoint, mention e mentionAll não existem aqui (stories não suportam menções na API).
  • Áudios em formatos não-Opus (mp3, m4a, wav) são convertidos automaticamente pelo servidor via FFmpeg para audio/ogg; codecs=opus antes de publicar. O processo pode aumentar o tempo de resposta da request.
  • Para type=video, o WhatsApp limita stories a ~30 segundos. Vídeos maiores podem ser cortados ou rejeitados pelo servidor do WhatsApp.
  • Status duram 24 horas e são apagados automaticamente. Para deletar antes, use o endpoint de apagar mensagem com o messageId retornado.
  • backgroundColor e font só fazem efeito em type=text. Em status de mídia, são ignorados silenciosamente.

​
Erros

HTTPStatus internoMensagem
400,Instance name is required
400,Invalid request body: <detalhe>
400,Type must be one of: text, image, video, audio
400,Message is required
400,MediaURL is required for type: <type>
400media_download_failedFailed to download media from URL
400media_validation_failed(validação do arquivo de mídia)
400unsupported_media_type(formato de mídia não suportado)
500media_upload_failedFailed to upload media to WhatsApp
500audio_conversion_failed(falha na conversão do áudio para Opus)
404,Instance not found
500send_failedFailed to send status: <reason>
503disconnectedInstance is not connected to WhatsApp
Envelope de erro: 
{
  "success": false,
  "error": { "message": "MediaURL is required for type: image" }
}