Console
Documentation/Send and receive messages

Send and receive messages

Message payloads, delivery states and idempotent sends.

Text messages

ts
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.

ts
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.

Prepared 18 November 2026 · Sqkii Pte. Ltd.