Send and receive messages
Message payloads, delivery states and idempotent sends.
Text messages
const accepted = await client.messages.send(
'number_id',
{ to: 'recipient_id', type: 'text', text: { body: 'Your order is ready.' } },
'order-123-ready',
);The request is POST /api/v1/numbers/{numberId}/messages with a required Idempotency-Key header. The response contains the platform message ID and its current status. Acceptance is not delivery; inspect subsequent events or fetch the message.
Delivery states
Messages progress through queued, sending, sent, delivered and read where reported by Meta. Failures include actionable error details. An uncertain upstream result is preserved for reconciliation; it is not an invitation to send again under a new key.
An outbound API message enters measured usage once delivered, including when a later read event proves delivery. Imported history and Business-app outbound echoes are excluded.
Service window and templates
For live free-form replies, a recent eligible customer message must open the service window. Historical imports do not open it. If the window is closed, use an approved template where required. The simulator cannot certify that a live template or recipient is eligible.
await client.messages.send('number_id', {
to: 'recipient_id', type: 'template',
template: { name: 'order_ready', language: { code: 'en' } },
}, 'order-123-template');Identity and provenance
Use the recipient identity provided for the authorized conversation. Do not assume it is always a phone number. New inbound messages, history, phone-app echoes, passive events and statuses have different operational meanings. Your agent should process only events appropriate to its workflow.
Attachments
Upload private media first and use the returned media identifier according to the media guide. Never expose a long-lived media URL or Meta access token to an end user.