Send Status

Auth: TokenAccount or TokenInstance • Rate-limit: Global (100/min) • Idempotent: no

Description

Publishes a status (story) lasting 24 hours on the instance’s profile. Supports four types: text (plain text with background color and font), image, video and audio. Unlike the other endpoints, there is no number field, the status is published to status@broadcast and is visible to every contact who has permission (configured on the app). Mentions are not supported on this endpoint.

Examples

Text status with color and font

Publishes a purely textual status with a custom background color and font. No mediaUrl is needed.

curl -X POST "https://ryzeapi.cloud/api/message/status/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "type":            "text",
    "message":         "May is here, and so are the new features!",
    "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:         "May is here, and so are the new features!",
    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":         "May is here, and so are the new features!",
        "backgroundColor": "#FF6600",
        "font":            "serif"
    }
)

package main

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

func main() {
    body := strings.NewReader(`{
        "type":            "text",
        "message":         "May is here, and so are the new features!",
        "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)
}

Image status

Publishes an image as a status. mediaUrl is required for non-text types. message is shown as the caption.

curl -X POST "https://ryzeapi.cloud/api/message/status/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "type":     "image",
    "message":  "New version launch!",
    "mediaUrl": "https://cdn.example.com/launch-banner.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:  "New version launch!",
    mediaUrl: "https://cdn.example.com/launch-banner.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":  "New version launch!",
        "mediaUrl": "https://cdn.example.com/launch-banner.jpg"
    }
)

package main

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

func main() {
    body := strings.NewReader(`{
        "type":     "image",
        "message":  "New version launch!",
        "mediaUrl": "https://cdn.example.com/launch-banner.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)
}

Video status

Publishes a short video as a status. WhatsApp caps video stories at 30 seconds, anything longer gets trimmed.

curl -X POST "https://ryzeapi.cloud/api/message/status/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "type":     "video",
    "message":  "Behind the scenes from this week's recording",
    "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:  "Behind the scenes from this week's recording",
    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":  "Behind the scenes from this week's recording",
        "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":  "Behind the scenes from this week's recording",
        "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)
}

Audio status (voice message)

Publishes audio as a status. By default it’s treated as PTT (voice). Use isVoice: false to handle it as a regular audio file.

curl -X POST "https://ryzeapi.cloud/api/message/status/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "type":     "audio",
    "message":  "Today's voice note",
    "mediaUrl": "https://cdn.example.com/voice-note.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:  "Today's voice note",
    mediaUrl: "https://cdn.example.com/voice-note.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":  "Today's voice note",
        "mediaUrl": "https://cdn.example.com/voice-note.ogg",
        "mimeType": "audio/ogg; codecs=opus",
        "isVoice":  True
    }
)

package main

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

func main() {
    body := strings.NewReader(`{
        "type":     "audio",
        "message":  "Today's voice note",
        "mediaUrl": "https://cdn.example.com/voice-note.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)
}

Success response

The messageType echoes the type you sent (text, image, video or audio) and chat.jid is always status@broadcast. The returned messageId can be used to delete the publication before the 24-hour window via the delete-message endpoint.

200 OK

{
  "success": true,
  "message": "Status sent successfully",
  "status":  "sent",
  "data": {
    "messageId":   "3EB08FCF27E532F1B0F5",
    "direction":   "sent",
    "messageType": "text",
    "content":     "May is here, and so are the new features!",
    "source":      "api",
    "timestamp":   "2026-04-30T14:30:00Z",
    "chat": {
      "jid":     "status@broadcast",
      "isGroup": false
    },
    "sender": {
      "jid":      "5511777777777@s.whatsapp.net",
      "instance": "my-instance"
    }
  }
}

Path parameters

string

required

Instance name (e.g., $Instance_Name).

Headers

string

required

TokenAccount or TokenInstance.

string

required

application/json

Request body

string

required

Status type. Accepted values: text, image, video, audio.

string

required

Textual content of the status. For type=text, this is the actual displayed text. For media (image, video, audio), it acts as the caption.

string

Public URL of the media file. Required when type is image, video or audio. Ignored when type=text.

string

MIME type of the media (e.g., image/jpeg, video/mp4, audio/ogg; codecs=opus). Optional, auto-detected when omitted.

string

File name. Optional, rarely relevant for stories.

string

For type=text only. Status background color in hex (e.g., #FF0000, #00AAFF). When omitted, WhatsApp uses the theme’s default color.

string

For type=text only. Text font. Common values: system, serif, sans-serif.

boolean

default:"true"

For type=audio only. When true (default), the audio is published as PTT (voice message). When false, it becomes a regular audio with the standard player.

uint32

For type=audio only. Duration in seconds. Optional, auto-detected by the transcoding tool.

byte[]

For type=audio only. Custom waveform (byte array). Optional, auto-generated if omitted.

string

default:"api"

Origin identifier for traceability (e.g., crm, marketing-bot, n8n).

Notes

There is no number field, stories always go to status@broadcast and become visible according to the privacy rules configured in the app (Settings → Privacy → Status).
Mentions are not supported on this endpoint, mention and mentionAll don’t exist here (stories don’t support mentions in the API).
Audio in non-Opus formats (mp3, m4a, wav) is automatically converted by the server through FFmpeg to audio/ogg; codecs=opus before publishing. The process can increase the request response time.
For type=video, WhatsApp caps stories at ~30 seconds. Longer videos may be trimmed or rejected by WhatsApp’s server.
Statuses last 24 hours and are deleted automatically. To delete sooner, use the delete-message endpoint with the returned messageId.
backgroundColor and font only take effect on type=text. On media statuses, they’re silently ignored.

Errors

HTTP	Internal status	Message
400	,	`Instance name is required`
400	,	`Invalid request body: <detail>`
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`	(media file validation)
400	`unsupported_media_type`	(unsupported media format)
500	`media_upload_failed`	`Failed to upload media to WhatsApp`
500	`audio_conversion_failed`	(failure converting audio to Opus)
404	,	`Instance not found`
500	`send_failed`	`Failed to send status: <reason>`
503	`disconnected`	`Instance is not connected to WhatsApp`

Error envelope:

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

Introduction

Instance

Events

Messages

Calls

Groups

Communities

Newsletter

Profile

Chat

Chatwoot

Typebot

Observability

Description

Examples

Text status with color and font

Image status

Video status

Audio status (voice message)

Success response

Path parameters

Headers

Request body

Notes

Errors

​Description

​Examples

​Text status with color and font

​Image status

​Video status

​Audio status (voice message)

​Success response

​Path parameters

​Headers

​Request body

​Notes

​Errors

Description

Examples

Text status with color and font

Image status

Video status

Audio status (voice message)

Success response

Path parameters

Headers

Request body

Notes

Errors