Enviar (o programar) un mensaje
POST/messages
El único camino de envío. Lo que cambia entre un texto y una plantilla es el
type del cuerpo, no la URL.
type | Para qué |
|---|---|
text | Texto libre. Solo dentro de la ventana de 24 h |
template | Plantilla aprobada. Abre conversación en cualquier momento |
test | Igual que template, con hello_world por defecto y errores traducidos |
¿Necesitas imagen, vídeo, documento, botones o carrusel? El camino es el espejo:
POST /v1/{phone_number_id}/messages acepta el payload completo de la Cloud API.
Programación. Con sendAt (instante ISO 8601) o delaySeconds (relativo), la
respuesta es 202 y el mensaje entra en la cola. El derecho de uso y el número se
vuelven a comprobar al enviar, no ahora.
Idempotencia. Con la cabecera Idempotency-Key, una repetición de la misma
llamada devuelve la primera respuesta, con Idempotent-Replayed: true, y no se envía
nada de nuevo — ni siquiera cuando la primera respuesta fue un error. La misma clave
con otro cuerpo se rechaza con 422 idempotency_key_reused; mientras la primera
solicitud sigue en curso, la repetición recibe 409 idempotency_in_progress.
Request
Responses
- 201
- 202
- 401
- 402
- 403
- 409
- 422
- 429
Registro encontrado.
Aceptado para envío posterior.
Token ausente, mal formado, desconocido o revocado (authentication), o cuenta
suspendida (tenant_inactive).
Sin derecho de uso (payment_required). El cuerpo trae el motivo en reason y la
salida en action: qué hacer (kind) y la página del panel donde se hace (url).
El recurso no pertenece a tu cuenta (forbidden), o la ruta está en la lista de
bloqueo del espejo (forbidden_endpoint), o tu API key está restringida a algunos
números y la operación es de toda la cuenta (forbidden).
Conflicto con el estado actual de la cuenta.
El payload no pasó la validación (invalid_request, detallado en issues) o fue
rechazado por Meta (meta_error, con el cuerpo original en meta).
Límite de peticiones superado (rate_limit).
Response Headers
Segundos a esperar antes de reintentar.
Categoría de límite aplicada — send, media o default.
Qué cubo describen las otras cabeceras — key (la API key), session (el panel) o account (el techo de la cuenta).
Techo de peticiones de la categoría en la ventana actual.
Peticiones restantes en la ventana actual.