post/messages— Send a message
Queues a text or media message to a user who opted in. Sandbox keys reach accepted testers only; internal_live apps reach their own organization (and may address by work email with a live key); public_live apps reach any organization that allows external businesses. Outside the 24h window after the user's last message an app may send at most 3 messages per user per 24h.
Scope: messages:send
Parameters
Idempotency-Key(header, string, required) — Required. Any unique string (<=255 printable ASCII). Kept 24h: same key + same body replays the first response; same key + different body is 422.
Request body
| Field | Type | Notes |
|---|---|---|
| torequired | object | object | |
| to (option 1).appUserIdrequired | string | Per-app user id, e.g. u_4f9XkQ2bT7mN1pR8sV0wYz · pattern ^u_[0-9A-Za-z]{22}$ |
| to (option 2).emailrequired | string (email) | internal_live apps with a live key only (D4) · max length 254 |
| typerequired | "text" | "image" | "video" | "audio" | "file" | |
| text | string | Required for text; caption for media · max length 4096 |
| mediaId | string | From POST /media; required for media types · min length 1 · max length 64 |
| clientReference | string | Echoed in message.status events · min length 1 · max length 128 |
Response 202 — Accepted
| Field | Type | Notes |
|---|---|---|
| idrequired | string | |
| statusrequired | "accepted" | |
| appUserIdrequired | string | Per-app user id, e.g. u_4f9XkQ2bT7mN1pR8sV0wYz · pattern ^u_[0-9A-Za-z]{22}$ |
| typerequired | "text" | "image" | "video" | "audio" | "file" | |
| createdAtrequired | string (date-time) | |
| clientReferencerequired | string | null |
Errors: 400 invalid_request / invalid_json / idempotency_key_required, 401 invalid_api_key, 403 insufficient_scope / app_suspended / key_environment_mismatch / consent_required / recipient_not_tester / recipient_outside_org / recipient_org_blocks_businesses / meetings_internal_only / meeting_access_not_enabled, 404 not_found / user_not_found, 409 idempotency_in_progress / media_not_uploaded, 422 idempotency_key_reused / media_invalid, 429 rate_limited / daily_quota_exceeded / business_initiated_cap / media_rate_limited. See error codes.