Skip to main content
POST
/
api
/
message
/
status
/
:instance
Send 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>"
}
'

Documentation Index

Fetch the complete documentation index at: https://docs.ryzeapi.cloud/llms.txt

Use this file to discover all available pages before exploring further.

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

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

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

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

​
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

​
instance
string
required
Instance name (e.g., $Instance_Name).

​
Headers

​
token
string
required
TokenAccount or TokenInstance.
​
Content-Type
string
required
application/json

​
Request body

​
type
string
required
Status type. Accepted values: text, image, video, audio.
​
message
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.
​
mediaUrl
string
Public URL of the media file. Required when type is image, video or audio. Ignored when type=text.
​
mimeType
string
MIME type of the media (e.g., image/jpeg, video/mp4, audio/ogg; codecs=opus). Optional, auto-detected when omitted.
​
fileName
string
File name. Optional, rarely relevant for stories.
​
backgroundColor
string
For type=text only. Status background color in hex (e.g., #FF0000, #00AAFF). When omitted, WhatsApp uses the theme’s default color.
​
font
string
For type=text only. Text font. Common values: system, serif, sans-serif.
​
isVoice
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.
​
duration
uint32
For type=audio only. Duration in seconds. Optional, auto-detected by the transcoding tool.
​
waveform
byte[]
For type=audio only. Custom waveform (byte array). Optional, auto-generated if omitted.
​
source
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

HTTPInternal statusMessage
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>
400media_download_failedFailed to download media from URL
400media_validation_failed(media file validation)
400unsupported_media_type(unsupported media format)
500media_upload_failedFailed to upload media to WhatsApp
500audio_conversion_failed(failure converting audio to Opus)
404—Instance not found
500send_failedFailed to send status: <reason>
503disconnectedInstance is not connected to WhatsApp
Error envelope: 
{
  "success": false,
  "error": { "message": "MediaURL is required for type: image" }
}