Publicar nuevo estado

Publica un nuevo estado de WhatsApp (también conocido como User Story o WhatsApp Story) usando texto, enlaces, imagen o video para el número de WhatsApp específico.

API de WhatsApp y CRM

Necesitas una clave de API. Pídela a nuestro equipo de soporte o créala desde la plataforma.

POST https://api.getincloud.ai/v1/chat/{deviceId}/status

Publica un nuevo estado de WhatsApp (también conocido como User Story o WhatsApp Story) usando texto, enlaces, imagen o video para el número de WhatsApp específico.

Opcionalmente puedes programar la actualización del estado de usuario en una fecha ISO concreta o usando un retraso en segundos o en notación de tiempo, por ejemplo: 2h, 1d, 7d.

Nota: la función de API de estados de WhatsApp solo está disponible en los planes Platform. Si quieres usarla, por favor [actualiza tu plan](/number/plan?product=io).

Cómo funciona el procesamiento de las actualizaciones de estado

Por defecto, las actualizaciones de estado de WhatsApp se procesan en tiempo real, a menos que se especifique como una actualización programada o retrasada.

Cuando las actualizaciones de estado se programan, se almacenan en una cola en orden primero en entrar, primero en salir (FIFO) no estricto.

Se puede forzar un orden estricto especificando el campo order = true en el cuerpo JSON (ejemplo).

¿Se pueden usar variables de plantilla en los mensajes de estado?

No, la sintaxis de variables de plantilla no es compatible con los mensajes de estado de usuario.

Tengo varios números conectados: ¿cómo envío mensajes a través de un número específico?

Si tienes varios números conectados a tu cuenta, debes especificar el campo device en el cuerpo JSON con el ID de dispositivo del número de WhatsApp de destino (valor hexadecimal de 24 caracteres) a través del cual quieres enviar los mensajes.

Si no se especifica el campo device, los mensajes se enviarán a través del primer número de WhatsApp conectado en tu cuenta.

Aquí tienes un ejemplo de cómo enviar un mensaje a través de un número de WhatsApp específico

Pruebas de la API en vivo con ejemplos

Ir al probador de API en vivo con decenas de ejemplos

Actualizar el estado de WhatsApp con texto

Actualizar el estado de WhatsApp con una imagen

Actualizar el estado de WhatsApp con un video

Programar una actualización del estado de WhatsApp

Programar una actualización retrasada del estado de WhatsApp

Programar una actualización del estado de WhatsApp con orden de publicación estricto

Prueba este endpoint en el probador de API en vivo

>¿Necesitas ayuda? Explora todos los tutoriales, más de 100 ejemplos de casos de uso y prueba el probador de API en vivo con ejemplos de código listos para usar en más de 15 lenguajes de programación, incluidos JavaScript/Node.js, PHP, Python, C#, Java, Ruby, Swift, Kotlin, Powershell, cURL y más.

Autenticación

Envía tu API key en el encabezado Token en cada petición.

Parámetros

Campo	Dónde	Tipo	Obligatorio	Descripción
`Idempotency-Key`	header	string	No	Encabezado opcional. La clave de idempotencia es un valor único generado por el cliente de la API que el servidor usa para reconocer reintentos posteriores de la misma solicitud. Cómo crear claves únicas depende de ti, pero sugerimos usar UUID V4 u otra cadena aleatoria con suficiente entropía para evitar colisiones. Si ya existe un mensaje con la misma clave de idempotencia, el servidor responderá con un estado `409 Conflict`, haciendo referencia al ID del mensaje existente en el error JSON de la respuesta, en el campo `meta.message`. `minimum: 6` · `maximum: 36`

Cuerpo de la petición

Campo	Tipo	Obligatorio	Descripción
`message`	string	No	Texto a enviar. Se permite la sintaxis de texto enriquecido de WhatsApp. Lee más sobre la sintaxis aquí. En chats grupales también puedes mencionar a los participantes usando la siguiente sintaxis: `@1234567890`, donde `1234567890` es el número de teléfono en formato E.164 del usuario participante. `minLength: 0` · `maxLength: 650`
`font`	string	No	Estilo de fuente a usar en el mensaje. Por defecto es `helvetica`. `enum: ['helvetica', 'serif', 'norican']`
`color`	string	No	Color de fondo a usar en el mensaje. Colores disponibles: - `red_purple` - `moss_green` - `dark_khaki` - `wine_red` - `light_taupe` - `goldenrod` - `olive_green` - `light_plum` - `dark_purple` - `light_coral` - `medium_sea_green` - `salmon` - `sky_blue` - `light_sky_blue` - `dark_taupe` - `slate_gray` - `dodger_blue` - `dark_magenta` - `seafoam_green` - `charcoal` - `periwinkle` `enum: ['red_purple', 'moss_green', 'dark_khaki', 'wine_red', 'light_taupe', 'goldenrod', 'olive_green', 'light_plum', 'dark_purple', 'light_coral', 'medium_sea_green', 'salmon', 'sky_blue', 'light_sky_blue', 'dark_taupe', 'slate_gray', 'dodger_blue', 'dark_magenta', 'seafoam_green', 'charcoal', 'periwinkle']`
`schedule`	object	No	Programación opcional de la actualización. Debe estar presente uno de los siguientes campos: `delay`, `delayTo` o `date`
`schedule.delay`	number	No	Programa la entrega del mensaje después de los segundos indicados. Por ejemplo: 300 `minimum: 1` · `maximum: 63072000` · `format: float`
`schedule.delayTo`	string	No	Programa la entrega del mensaje usando la sintaxis de duración de tiempo. Ejemplos de valores válidos: 1h, 15m, 12h, 1d. Lee más sobre la sintaxis de duración aquí. `minLength: 2` · `maxLength: 5` · `pattern: ^([0-9]{1,8})([y`
`schedule.date`	string	No	Programa la entrega del mensaje en una fecha y hora personalizadas en formato ISO 8601. Por ejemplo: 2019-01-23T23:22:59.776Z `format: date-time`
`reference`	string	No	Referencia opcional del mensaje definida por el usuario para facilitar la trazabilidad con sistemas existentes. Por ejemplo, puedes definir como referencia el ID del cliente en tu CRM. El valor de `reference` se incluirá en cada evento de webhook. `minLength: 1` · `maxLength: 150`
`media`	object	No	Actualiza el estado de usuario con una imagen o video (jpeg, png, webp, mp4)
`media.file`	string	No	ID del archivo subido para enviar como contenido multimedia del mensaje. El archivo debe haberse subido previamente usando el [endpoint de la API para subir archivos](#tag/Files/operation/uploadFile) y obteniendo el ID único del archivo (valor alfanumérico de 24 caracteres). Importante: no puedes poner aquí el contenido del archivo. Como alternativa, puedes enviar un archivo multimedia usando el campo `media.url` especificando una URL pública accesible del archivo (consulta el campo `url` más abajo). `minLength: 24` · `maxLength: 24` · `pattern: ^[0-9A-Fa-f]{24}$`
`media.url`	string	No	URL pública accesible desde Internet para descargar el contenido del archivo. Si la URL devuelve un error, no es accesible desde Internet o el tipo de archivo no es válido, la API devolverá un error `400 Bad Request`. `minLength: 10` · `maxLength: 1024`
`media.message`	string	No	Pie de texto opcional del archivo multimedia que se usará al entregar el mensaje. Solo aplica a archivos de imagen y video; en otros casos se ignora. Se usa cuando no hay un campo de cuerpo de mensaje definido en el mensaje que se va a entregar. `minLength: 0` · `maxLength: 15000`
`media.filename`	string	No	Nombre de archivo opcional. Si no se define, se toma de la URL del archivo o del contenido del formulario, si está disponible. De lo contrario, se generará un nombre de archivo aleatorio. `minLength: 3` · `maxLength: 200`
`media.reference`	string	No	Identificador de referencia opcional del archivo definido por el usuario. Puede ser útil para identificar archivos entre sistemas, por ejemplo, un CRM o un sistema de almacenamiento. `minLength: 2` · `maxLength: 150`
`media.format`	string	No	Formato de visualización opcional del archivo, cuando aplique para GIF (videos) y grabaciones de voz (audios) `enum: ['gif', 'ptt', 'native']` · `default: native`
`media.permission`	string	No	Permiso de acceso opcional al archivo. Por defecto es `public`: todos los miembros del equipo pueden acceder, descargar y enviar el archivo. Si se establece en `private`, solo el propietario del archivo puede acceder, descargar y enviar el archivo. `enum: ['public', 'readonly', 'private']`
`media.tags`	array<string>	No	Etiquetas opcionales del archivo, hasta 10 etiquetas por archivo. Cada etiqueta no puede tener más de 50 caracteres.
`media.expiration`	string	No	Límite de tiempo de almacenamiento del archivo, después del cual se eliminará del sistema. Por defecto es 15 días. `enum: ['10m', '30m', '1h', '6h', '12h', '1d', '2d', '3d', '5d', '6d', '7d', '15d', '30d', '60d', '90d', '120d', '180d', '360d', '1y', '2y']` · `minLength: 2` · `maxLength: 5` · `default: 30d`

Respuestas

Código	Descripción
`201`	Mensaje creado
`400`	Solicitud incorrecta
`401`	No autorizado
`403`	El estado de la cola no permite encolar ni entregar nuevos mensajes
`404`	El número de teléfono no existe en WhatsApp
`409`	Conflicto: el mensaje ya existe
`429`	Demasiadas solicitudes
`500`	Error del servidor
`501`	No implementado
`503`	Servicio no disponible

// This code example requires you to have installed curl package
// Installation instructions here: https://curl.haxx.se/download.html

// Publish a new WhatsApp status with a text message and background color
curl --request POST \
  --url https://api.getincloud.ai/v1/chat/{device.id}/status \
  --header 'Content-Type: application/json' \
  --header 'Token: <api token goes here>' \
  --data '{"message":"This is an automated WhatsApp status update: https://youtube.com","font":"helvetica","color":"olive_green"}'


// Publish a new WhatsApp status with an image and caption
curl --request POST \
  --url https://api.getincloud.ai/v1/chat/{device.id}/status \
  --header 'Content-Type: application/json' \
  --header 'Token: <api token goes here>' \
  --data '{"message":"This is an automated WhatsApp status with image","media":{"url":"https://picsum.photos/seed/picsum/600/400"}}'


// Publish a new WhatsApp status with an video and caption
curl --request POST \
  --url https://api.getincloud.ai/v1/chat/{device.id}/status \
  --header 'Content-Type: application/json' \
  --header 'Token: <api token goes here>' \
  --data '{"message":"This is an automated WhatsApp status with video","media":{"url":"https://download.samplelib.com/mp4/sample-5s.mp4"}}'


// Publish a new WhatsApp status with a scheduled delivery based on time unit
curl --request POST \
  --url https://api.getincloud.ai/v1/chat/{device.id}/status \
  --header 'Content-Type: application/json' \
  --header 'Token: <api token goes here>' \
  --data '{"message":"This is an scheduled WhatsApp status update for tomorrow","schedule":{"delayTo":"1h"},"media":{"url":"https://picsum.photos/seed/picsum/600/400"}}'


// Publish a new WhatsApp status with a scheduled delivery
curl --request POST \
  --url https://api.getincloud.ai/v1/chat/{device.id}/status \
  --header 'Content-Type: application/json' \
  --header 'Token: <api token goes here>' \
  --data '{"message":"This is an scheduled WhatsApp status update using an ISO date","schedule":{"date":"2026-10-05T14:52:47.587Z"},"media":{"url":"https://picsum.photos/seed/picsum/600/400"}}'


// Publish a new WhatsApp status with a scheduled delivery in strict order
curl --request POST \
  --url https://api.getincloud.ai/v1/chat/{device.id}/status \
  --header 'Content-Type: application/json' \
  --header 'Token: <api token goes here>' \
  --data '{"message":"This is an scheduled WhatsApp status update using an ISO date","order":true,"schedule":{"date":"2026-10-05T14:52:47.587Z"},"media":{"url":"https://picsum.photos/seed/picsum/600/400"}}'

AnteriorObtener participantes de un grupo SiguienteSincronizar chats

¿Te sirvió esta página?