Enviar Status

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"
  }'

await fetch(`https://ryzeapi.cloud/api/message/status/${process.env.Instance_Name}`, {
  method: "POST",
  headers: {
    "token":        process.env.Token_Instance,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    type:            "text",
    message:         "Estamos chegando em Maio com novidades!",
    backgroundColor: "#FF6600",
    font:            "serif"
  })
});

import os, requests

requests.post(
    f"https://ryzeapi.cloud/api/message/status/{os.environ['Instance_Name']}",
    headers={
        "token":        os.environ["Token_Instance"],
        "Content-Type": "application/json"
    },
    json={
        "type":            "text",
        "message":         "Estamos chegando em Maio com novidades!",
        "backgroundColor": "#FF6600",
        "font":            "serif"
    }
)

package main

import (
    "net/http"
    "os"
    "strings"
)

func main() {
    body := strings.NewReader(`{
        "type":            "text",
        "message":         "Estamos chegando em Maio com novidades!",
        "backgroundColor": "#FF6600",
        "font":            "serif"
    }`)
    req, _ := http.NewRequest("POST", "https://ryzeapi.cloud/api/message/status/"+os.Getenv("Instance_Name"), body)
    req.Header.Set("token", os.Getenv("Token_Instance"))
    req.Header.Set("Content-Type", "application/json")
    http.DefaultClient.Do(req)
}

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"
  }'

await fetch(`https://ryzeapi.cloud/api/message/status/${process.env.Instance_Name}`, {
  method: "POST",
  headers: {
    "token":        process.env.Token_Instance,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    type:     "image",
    message:  "Lançamento da nova versão!",
    mediaUrl: "https://cdn.example.com/banner-lancamento.jpg"
  })
});

import os, requests

requests.post(
    f"https://ryzeapi.cloud/api/message/status/{os.environ['Instance_Name']}",
    headers={
        "token":        os.environ["Token_Instance"],
        "Content-Type": "application/json"
    },
    json={
        "type":     "image",
        "message":  "Lançamento da nova versão!",
        "mediaUrl": "https://cdn.example.com/banner-lancamento.jpg"
    }
)

package main

import (
    "net/http"
    "os"
    "strings"
)

func main() {
    body := strings.NewReader(`{
        "type":     "image",
        "message":  "Lançamento da nova versão!",
        "mediaUrl": "https://cdn.example.com/banner-lancamento.jpg"
    }`)
    req, _ := http.NewRequest("POST", "https://ryzeapi.cloud/api/message/status/"+os.Getenv("Instance_Name"), body)
    req.Header.Set("token", os.Getenv("Token_Instance"))
    req.Header.Set("Content-Type", "application/json")
    http.DefaultClient.Do(req)
}

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"
  }'

await fetch(`https://ryzeapi.cloud/api/message/status/${process.env.Instance_Name}`, {
  method: "POST",
  headers: {
    "token":        process.env.Token_Instance,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    type:     "video",
    message:  "Bastidores da gravação desta semana",
    mediaUrl: "https://cdn.example.com/teaser.mp4",
    mimeType: "video/mp4"
  })
});

import os, requests

requests.post(
    f"https://ryzeapi.cloud/api/message/status/{os.environ['Instance_Name']}",
    headers={
        "token":        os.environ["Token_Instance"],
        "Content-Type": "application/json"
    },
    json={
        "type":     "video",
        "message":  "Bastidores da gravação desta semana",
        "mediaUrl": "https://cdn.example.com/teaser.mp4",
        "mimeType": "video/mp4"
    }
)

package main

import (
    "net/http"
    "os"
    "strings"
)

func main() {
    body := strings.NewReader(`{
        "type":     "video",
        "message":  "Bastidores da gravação desta semana",
        "mediaUrl": "https://cdn.example.com/teaser.mp4",
        "mimeType": "video/mp4"
    }`)
    req, _ := http.NewRequest("POST", "https://ryzeapi.cloud/api/message/status/"+os.Getenv("Instance_Name"), body)
    req.Header.Set("token", os.Getenv("Token_Instance"))
    req.Header.Set("Content-Type", "application/json")
    http.DefaultClient.Do(req)
}

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
  }'

await fetch(`https://ryzeapi.cloud/api/message/status/${process.env.Instance_Name}`, {
  method: "POST",
  headers: {
    "token":        process.env.Token_Instance,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    type:     "audio",
    message:  "Recado de hoje",
    mediaUrl: "https://cdn.example.com/recado.ogg",
    mimeType: "audio/ogg; codecs=opus",
    isVoice:  true
  })
});

import os, requests

requests.post(
    f"https://ryzeapi.cloud/api/message/status/{os.environ['Instance_Name']}",
    headers={
        "token":        os.environ["Token_Instance"],
        "Content-Type": "application/json"
    },
    json={
        "type":     "audio",
        "message":  "Recado de hoje",
        "mediaUrl": "https://cdn.example.com/recado.ogg",
        "mimeType": "audio/ogg; codecs=opus",
        "isVoice":  True
    }
)

package main

import (
    "net/http"
    "os"
    "strings"
)

func main() {
    body := strings.NewReader(`{
        "type":     "audio",
        "message":  "Recado de hoje",
        "mediaUrl": "https://cdn.example.com/recado.ogg",
        "mimeType": "audio/ogg; codecs=opus",
        "isVoice":  true
    }`)
    req, _ := http.NewRequest("POST", "https://ryzeapi.cloud/api/message/status/"+os.Getenv("Instance_Name"), body)
    req.Header.Set("token", os.Getenv("Token_Instance"))
    req.Header.Set("Content-Type", "application/json")
    http.DefaultClient.Do(req)
}

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

string

obrigatório

Nome da instância (ex.: $Instance_Name).

Headers

string

obrigatório

TokenAccount ou TokenInstance.

string

obrigatório

application/json

Request body

string

obrigatório

Tipo do status. Valores aceitos: text, image, video, audio.

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.

string

URL pública do arquivo de mídia. Obrigatório quando type é image, video ou audio. Ignorado quando type=text.

string

MIME type da mídia (ex.: image/jpeg, video/mp4, audio/ogg; codecs=opus). Opcional, auto-detectado quando omitido.

string

Nome do arquivo. Opcional, raramente relevante para stories.

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.

string

Apenas para type=text. Fonte do texto. Valores comuns: system, serif, sans-serif.

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.

uint32

Apenas para type=audio. Duração em segundos. Opcional, auto-detectado pela ferramenta de transcodificação.

byte[]

Apenas para type=audio. Forma de onda customizada (array de bytes). Opcional, auto-gerada se omitida.

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

HTTP	Status interno	Mensagem
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>`
400	`media_download_failed`	`Failed to download media from URL`
400	`media_validation_failed`	(validação do arquivo de mídia)
400	`unsupported_media_type`	(formato de mídia não suportado)
500	`media_upload_failed`	`Failed to upload media to WhatsApp`
500	`audio_conversion_failed`	(falha na conversão do áudio para Opus)
404	,	`Instance not found`
500	`send_failed`	`Failed to send status: <reason>`
503	`disconnected`	`Instance is not connected to WhatsApp`

Envelope de erro:

{
  "success": false,
  "error": { "message": "MediaURL is required for type: image" }
}

Introdução

Instância

Eventos

Mensagens

Chamadas

Grupos

Comunidades

Newsletter

Perfil

Chat

Chatwoot

Typebot

Observabilidade

Descrição

Exemplos

Status de texto com cor e fonte

Status de imagem

Status de vídeo

Status de áudio (mensagem de voz)

Resposta de sucesso

Parâmetros de rota

Headers

Request body

Notas

Erros

​Descrição

​Exemplos

​Status de texto com cor e fonte

​Status de imagem

​Status de vídeo

​Status de áudio (mensagem de voz)

​Resposta de sucesso

​Parâmetros de rota

​Headers

​Request body

​Notas

​Erros

Descrição

Exemplos

Status de texto com cor e fonte

Status de imagem

Status de vídeo

Status de áudio (mensagem de voz)

Resposta de sucesso

Parâmetros de rota

Headers

Request body

Notas

Erros