Send message
Send a message in a conversation. Supports text, attachments, quick replies, buttons, templates, and message tags. Attachment and interactive message support varies by platform.
WhatsApp per-recipient rate limit: WhatsApp caps how many messages you may send to the same recipient in a short window and rejects the excess with error code 131056 ("Too many messages sent to this recipient"). Pace sends to a single recipient at roughly 10 per minute; bursts above that return a 400 with code 131056. Sends to other recipients are unaffected, so parallelise across recipients rather than flooding one.
iMessage pacing: messages to contacts who have not written to the sender in the last 24 hours must be at least 2 minutes apart per sender; a send inside that window returns 429 with code new_contact_limit and the time to retry. Replies to contacts who wrote within the last day are not paced. A thread opened with POST /v1/inbox/conversations takes at most two follow-ups before the contact replies, at least 24 hours apart (429 new_contact_limit sooner, 409 recipient_must_message_first for a fourth message). Each such follow-up counts as a new conversation: no links, emails, phone numbers, prices or attachments (400 invalid_content), and it uses the sender's 15-minute spacing and daily warm-up (429 new_contact_limit). Text must be shorter than 10,000 characters.
WhatsApp template messages: to send an approved template into this conversation (required when the 24-hour customer-service window is closed), use the template field with a single element carrying the template reference: { "elements": [{ "name": ..., "language": ..., "components": [...] }] }. See the template field below for the exact shape. To send a template to a phone number you have no conversation with yet, use the create-conversation endpoint (POST /v1/inbox/conversations) instead.
Zernio resolves the exact APPROVED template name and language before any WhatsApp template send. A failed lookup or missing exact definition sends no message and returns code platform_api_error, type platform_error, and platform whatsapp. Sanitized Meta code, message, and error_data.details are returned in platformError; details identifies phase: template_lookup, the query-free endpoint, upstream status, and only safe provider usage or retry headers.
WhatsApp rich interactive messages (list, CTA URL, Flow, location request) are available via the interactive field. Tap events are delivered through the message.received webhook with WhatsApp-specific metadata fields (interactiveType, interactiveId, flowResponseJson, flowResponseData).
Idempotency: send an Idempotency-Key header to make retries safe (e.g. after a client-side timeout where delivery is unknown): same key + same body replays the original response (with Idempotent-Replayed: true) instead of sending the message a second time; same key + different body returns 422; a key still in flight returns 409. Works for JSON and multipart (file upload) requests alike. Keys are retained for 24 hours.
Only successful (2xx) responses are stored for replay: if the request throws or returns a non-2xx status, the key is released so the same key can be retried once the problem is fixed. The header therefore protects the "request succeeded but the response was lost" case. For an ambiguous failure (a 5xx or a network timeout), reconcile before retrying: a failure after the platform already accepted the message also releases the key, and a blind retry could send it twice. List the conversation's messages first, and treat an empty result as inconclusive rather than as proof nothing was sent, since a send that failed while being recorded leaves no trace on our side.
Path parameters
Opaque conversation identifier, accepted verbatim from the list endpoint or from the conversationId on inbox webhooks. Format not to be assumed.
Headers
Optional client-generated unique key (e.g. a UUID) that makes retries safe. Same key + same body replays the original response; same key + different body → 422; key still processing → 409.
Request body
Response
Message sent