Enviar status

Auth: TokenAccount o TokenInstance • Rate-limit: Global (100/min) • Idempotente: no

Descripción

Publica un status (historia) con duración de 24 horas en el perfil de la instancia. Soporta cuatro tipos: text (texto plano con color de fondo y fuente), image, video y audio. A diferencia de los demás endpoints, no hay campo number, el status se publica en status@broadcast y es visible para todos los contactos que tengan permiso (configurado en la app). Las menciones no son soportadas en este endpoint.

Ejemplos

Status de texto con color y fuente

Publica un status puramente textual con color de fondo y fuente personalizados. No se necesita 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":         "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)
}

Status de imagen

Publica una imagen como status. mediaUrl es requerido para tipos no-texto. message se muestra como subtítulo.

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

Status de video

Publica un video corto como status. WhatsApp limita las historias de video a 30 segundos, los más largos se recortan.

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

Status de audio (mensaje de voz)

Publica audio como status. Por defecto se trata como PTT (voz). Usa isVoice: false para manejarlo como un archivo de audio regular.

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

Respuesta exitosa

El messageType refleja el type que enviaste (text, image, video o audio) y chat.jid siempre es status@broadcast. El messageId retornado puede usarse para eliminar la publicación antes de la ventana de 24 horas vía el endpoint de eliminar mensaje.

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

Parámetros de ruta

string

requerido

Nombre de la instancia (p. ej., $Instance_Name).

Cabeceras

string

requerido

TokenAccount o TokenInstance.

string

requerido

application/json

Cuerpo de la solicitud

string

requerido

Tipo de status. Valores aceptados: text, image, video, audio.

string

requerido

Contenido textual del status. Para type=text, este es el texto efectivamente mostrado. Para media (image, video, audio), funciona como subtítulo.

string

URL pública del archivo de media. Requerido cuando type es image, video o audio. Ignorado cuando type=text.

string

Tipo MIME de la media (p. ej., image/jpeg, video/mp4, audio/ogg; codecs=opus). Opcional, autodetectado cuando se omite.

string

Nombre del archivo. Opcional, raramente relevante para historias.

string

Solo para type=text. Color de fondo del status en hex (p. ej., #FF0000, #00AAFF). Cuando se omite, WhatsApp usa el color default del tema.

string

Solo para type=text. Fuente del texto. Valores comunes: system, serif, sans-serif.

boolean

predeterminado:"true"

Solo para type=audio. Cuando es true (default), el audio se publica como PTT (mensaje de voz). Cuando es false, se vuelve un audio regular con el reproductor estándar.

uint32

Solo para type=audio. Duración en segundos. Opcional, autodetectada por la herramienta de transcoding.

byte[]

Solo para type=audio. Waveform personalizada (array de bytes). Opcional, autogenerada si se omite.

string

predeterminado:"api"

Identificador de origen para trazabilidad (p. ej., crm, marketing-bot, n8n).

Notas

No hay campo number, las historias siempre van a status@broadcast y se vuelven visibles según las reglas de privacidad configuradas en la app (Configuración → Privacidad → Status).
Las menciones no son soportadas en este endpoint, mention y mentionAll no existen aquí (las historias no soportan menciones en la API).
El audio en formatos no-Opus (mp3, m4a, wav) es convertido automáticamente por el servidor a través de FFmpeg a audio/ogg; codecs=opus antes de publicar. El proceso puede aumentar el tiempo de respuesta de la solicitud.
Para type=video, WhatsApp limita las historias a ~30 segundos. Los videos más largos pueden ser recortados o rechazados por el servidor de WhatsApp.
Los status duran 24 horas y se eliminan automáticamente. Para eliminarlos antes, usa el endpoint de eliminar mensaje con el messageId retornado.
backgroundColor y font solo tienen efecto en type=text. En status de media, son ignorados silenciosamente.

Errores

HTTP	Status interno	Mensaje
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`	(validación del archivo de media)
400	`unsupported_media_type`	(formato de media no soportado)
500	`media_upload_failed`	`Failed to upload media to WhatsApp`
500	`audio_conversion_failed`	(fallo al convertir audio a Opus)
404	,	`Instance not found`
500	`send_failed`	`Failed to send status: <reason>`
503	`disconnected`	`Instance is not connected to WhatsApp`

Envoltorio de error:

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

Introducción

Instancia

Eventos

Mensajes

Llamadas

Grupos

Comunidades

Newsletter

Perfil

Chat

Chatwoot

Typebot

Observabilidad

Descripción

Ejemplos

Status de texto con color y fuente

Status de imagen

Status de video

Status de audio (mensaje de voz)

Respuesta exitosa

Parámetros de ruta

Cabeceras

Cuerpo de la solicitud

Notas

Errores

​Descripción

​Ejemplos

​Status de texto con color y fuente

​Status de imagen

​Status de video

​Status de audio (mensaje de voz)

​Respuesta exitosa

​Parámetros de ruta

​Cabeceras

​Cuerpo de la solicitud

​Notas

​Errores

Descripción

Ejemplos

Status de texto con color y fuente

Status de imagen

Status de video

Status de audio (mensaje de voz)

Respuesta exitosa

Parámetros de ruta

Cabeceras

Cuerpo de la solicitud

Notas

Errores