curl --request POST \
  --url https://api.wppfy.com/send/status \
  --header 'Content-Type: application/json' \
  --header 'token: <api-key>' \
  --data '
{
  "type": "text",
  "text": "Novidades chegando!"
}
'

{
  "Id": "ABCD1234",
  "content": {},
  "messageTimestamp": 1672531200000,
  "status": "Pending",
  "debug": {
    "status_privacy_type": "contacts",
    "audience_recipient_count": 245,
    "total_contacts_in_store": 300,
    "contacts_with_full_name": 245,
    "contacts_with_push_name_only": 32,
    "contacts_with_business_name_only": 23,
    "used_default_privacy_fallback": false,
    "privacy_lookup_error": "privacy unavailable",
    "explicit_recipients": true,
    "requested_recipient_count": 25,
    "resolved_recipient_count": 20,
    "discarded_recipient_count": 5,
    "discarded_recipients": [
      {
        "input": "144637553594388@lid",
        "reason": "lid_unresolved"
      }
    ],
    "max_recipients": 100,
    "selected_recipient_count": 100,
    "partial_send": true
  }
}

{
  "error": "Fuente inválida",
  "debug": {}
}

{
  "error": "failed to determine status audience: privacy unavailable"
}

Enviar Mensaje

Enviar estado (stories)

Envía un estado de WhatsApp con soporte para texto, imagen, video y audio.

Este endpoint tiene 4 modos de uso:

envío normal: omita recipients, max_recipients y group
envío explícito: indique recipients para enviar solo a números específicos; la API aprovecha los válidos y descarta los inválidos con el motivo en debug
envío parcial: indique max_recipients para limitar la audiencia o aplicar un límite de seguridad sobre recipients
estado de grupo: indique group con el JID del grupo (@g.us)

Observación importante sobre `recipients`

Cuando se indica recipients, la API:

acepta números en formato WhatsApp, JIDs @s.whatsapp.net y JIDs @lid
cuando recibe @lid, intenta resolver ese identificador al PN (@s.whatsapp.net) usando los vínculos conocidos por la instancia
si el @lid no puede resolverse a un PN, ese elemento se descarta con el motivo lid_unresolved
valida si el destinatario existe en WhatsApp usando el mismo flujo de verificación del envío normal, en lotes para evitar una llamada remota por destinatario
cruza los destinatarios verificados con la audiencia permitida por la privacidad del estado, aceptando equivalencia PN/LID cuando ese vínculo es conocido
los destinatarios descartados aparecen en debug.discarded_recipients, con motivos como invalid_format, lid_unresolved, not_on_whatsapp, outside_status_audience y duplicate
la solicitud solo devuelve 400 cuando no queda ningún destinatario válido para el envío

Observación importante sobre `max_recipients`

El campo max_recipients se agregó como mitigación operativa. Ya hemos observado casos en los que WhatsApp bloquea inmediatamente el envío de estados cuando la audiencia es muy grande (por ejemplo, agendas con miles de contactos, como ~3.000). La causa exacta aún no está totalmente clara, por lo que se recomienda comenzar con límites menores y aumentarlos gradualmente.

Estado de grupo

Con group, el estado se publica en el grupo y aparece para los miembros en la pestaña Estados, en lugar del estado de la cuenta. La cuenta debe participar en el grupo. Aplica a texto, imagen y video: el audio (audio, ptt y myaudio) no funciona en el estado de grupo y devuelve 400.

no se combina con recipients ni con max_recipients (devuelve 400)
la respuesta incluye Id, content, messageTimestamp y status, sin debug

Tipos soportados

text: texto con color de fondo y fuente
image: imagen con leyenda opcional
video: video con leyenda opcional
audio: audio normal
myaudio: audio enviado como voz
ptt: audio enviado como voz

Colores de fondo

Indique un valor de 1 a 19. La API convierte este índice al color usado por WhatsApp.

1: amarillo verdoso suave
2: amarillo pálido
3: amarillo anaranjado vibrante
4: verde vibrante
5: verde musgo
6: verde claro
7: azul piscina
8: azul intenso
9: azul claro grisáceo
10: lila claro
11: lila cálido
12: púrpura azulado
13: magenta profundo
14: rosa suave
15: salmón rosado
16: marrón claro
17: gris claro azulado
18: gris medio
19: gris profundo predeterminado

Ejemplo rápido:

7: azul piscina
13: magenta profundo
19: gris profundo (predeterminado)

Fuentes válidas para `type=text`

Valores aceptados actualmente: 0, 1, 2, 6, 7, 8, 9, 10.

Límites

text: máximo de 656 caracteres
max_recipients: no puede ser negativo
recipients: acepta números, JIDs @s.whatsapp.net y JIDs @lid
@lid solo se incluye en el envío cuando puede resolverse localmente a un PN válido; de lo contrario, se descarta
para tipos de medios, file es obligatorio
group: JID del grupo (@g.us)

Ejemplo de envío explícito:

{
  "type": "text",
  "text": "Novidades chegando!",
  "recipients": [
    "5511999999999",
    "5511888888888@s.whatsapp.net"
  ]
}

Ejemplo de envío parcial:

{
  "type": "text",
  "text": "Novidades chegando!",
  "background_color": 7,
  "font": 1,
  "max_recipients": 100
}

Ejemplo de estado de grupo:

{
  "type": "image",
  "file": "https://exemplo.com/status.jpg",
  "text": "Aviso para o grupo",
  "group": "120363123456789012@g.us"
}

POST

send

status

curl --request POST \
  --url https://api.wppfy.com/send/status \
  --header 'Content-Type: application/json' \
  --header 'token: <api-key>' \
  --data '
{
  "type": "text",
  "text": "Novidades chegando!"
}
'

{
  "Id": "ABCD1234",
  "content": {},
  "messageTimestamp": 1672531200000,
  "status": "Pending",
  "debug": {
    "status_privacy_type": "contacts",
    "audience_recipient_count": 245,
    "total_contacts_in_store": 300,
    "contacts_with_full_name": 245,
    "contacts_with_push_name_only": 32,
    "contacts_with_business_name_only": 23,
    "used_default_privacy_fallback": false,
    "privacy_lookup_error": "privacy unavailable",
    "explicit_recipients": true,
    "requested_recipient_count": 25,
    "resolved_recipient_count": 20,
    "discarded_recipient_count": 5,
    "discarded_recipients": [
      {
        "input": "144637553594388@lid",
        "reason": "lid_unresolved"
      }
    ],
    "max_recipients": 100,
    "selected_recipient_count": 100,
    "partial_send": true
  }
}

{
  "error": "Fuente inválida",
  "debug": {}
}

{
  "error": "failed to determine status audience: privacy unavailable"
}

Autorizaciones

token

string

header

requerido

Cuerpo

application/json

type

enum<string>

requerido

Tipo del estado.

Opciones disponibles:

text,

image,

video,

audio,

myaudio,

ptt

Ejemplo:

"text"

text

string

Texto principal o leyenda.

Ejemplo:

"¡Novedades en camino!"

background_color

integer

Índice del color de fondo para estado de texto.

Rango requerido: 1 <= x <= 19

Ejemplo:

7

font

enum<integer>

Fuente aceptada para type=text.

Opciones disponibles:

0,

1,

2,

6,

7,

8,

9,

10

Ejemplo:

1

file

string

URL o base64 del archivo multimedia.

Ejemplo:

"https://example.com/video.mp4"

thumbnail

string

Campo aceptado en el payload; la API genera la miniatura automáticamente cuando es necesario.

Ejemplo:

"https://example.com/thumb.jpg"

mimetype

string

MIME type del archivo, cuando sea necesario.

Ejemplo:

"video/mp4"

recipients

string[]

Lista explícita de destinatarios. Acepta números en formato de WhatsApp, JIDs @s.whatsapp.net y JIDs @lid. La API valida elemento por elemento, descarta los inválidos con el motivo en debug y envía al subconjunto válido restante. Las entradas @lid dependen de una resolución conocida a PN.

Ejemplo:

[
  "5511999999999",
  "5511888888888@s.whatsapp.net"
]

max_recipients

integer

Limita el envío a un subconjunto determinístico de la audiencia. Cuando se informa recipients, funciona como límite de seguridad sobre la lista explícita ya validada.

Rango requerido: x >= 0

Ejemplo:

100

group

string

JID del grupo (@g.us). Publica el estado en el grupo, para los miembros, en lugar del estado de la cuenta. No se combina con recipients ni max_recipients. Solo texto, imagen y video: el audio devuelve 400.

Ejemplo:

"120363123456789012@g.us"

Respuesta

Estado enviado con éxito

string

ID del mensaje cuando hay un envío real.

Ejemplo:

"ABCD1234"

content

object

Contenido procesado del mensaje cuando hay un envío real.

messageTimestamp

integer

Timestamp en milisegundos cuando hay un envío real.

Ejemplo:

1672531200000

status

string

Estado del envío cuando hay un envío real.

Ejemplo:

"Pending"

debug

object

Métricas agregadas de la audiencia y de la selección aplicada.

Show child attributes

Instancia

CRM

Proxy

Perfil

Enviar Mensaje

Mensaje Async

Acciones en el mensaje y Búsqueda

Grupos y Comunidades

Newsletters y Canales

Server-Sent Events (SSE)

Bloqueos

Etiquetas

Chats

Contactos

Llamadas

Integración con Chatwoot

Business

Respuestas Rápidas

Enviar estado (stories)

Observación importante sobre `recipients`

Observación importante sobre `max_recipients`

Estado de grupo

Tipos soportados

Colores de fondo

Fuentes válidas para `type=text`

Límites

Autorizaciones

Cuerpo

Respuesta