Send (or schedule) a message
POST/messages
The one way to send. What changes between a text and a template is type in the
body — not the URL.
type | What for |
|---|---|
text | Free text. Only inside the 24-hour window |
template | Approved template. Opens a conversation at any time |
test | Same as template, defaulting to hello_world with translated errors |
Need an image, a video, a document, buttons or a carousel? The mirror is the way:
POST /v1/{phone_number_id}/messages takes the full Cloud API payload, with any
type Meta supports.
Scheduling. With sendAt (an ISO 8601 instant) or delaySeconds (relative),
the answer is 202 and the message goes on the queue. Entitlement and phone number
are re-checked at send time, not now.
Idempotency. With the Idempotency-Key header, a repeat of the same call returns
the first answer, with Idempotent-Replayed: true, and nothing is sent again — not
even when the first answer was an error. The same key with another body is refused
with 422 idempotency_key_reused; while the first request is still running, the
repeat gets 409 idempotency_in_progress.
Request
Responses
- 201
- 202
- 401
- 402
- 403
- 409
- 422
- 429
Record found.
Accepted for later delivery.
Missing, malformed, unknown or revoked token (authentication), or a suspended
account (tenant_inactive).
No entitlement (payment_required). The body carries the reason in reason and the
way out in action: what to do (kind) and the dashboard page where it is done (url).
The resource does not belong to your account (forbidden), or the path is on the
mirror's block list (forbidden_endpoint), or your API key is limited to some numbers and
the operation covers the whole account (forbidden).
Conflicts with the current state of the account.
Payload failed validation (invalid_request, detailed in issues) or was
rejected by Meta (meta_error, with the original body in meta).
Rate limit exceeded (rate_limit).
Response Headers
Seconds to wait before retrying.
Which rate limit category applied — send, media or default.
Which bucket the other headers describe — key (the API key), session (the dashboard) or account (the account ceiling).
Request ceiling for this category in the current window.
Requests left in the current window.