Skip to navigation
API ReferenceMessages

Send a message (SMS or WhatsApp)

Sends an SMS or free-form WhatsApp message. Returns 201 with the Message object; you track delivery via the message.* webhooks you already receive.

The status field reflects how the send was handled:

  • sent — handed to the carrier/provider synchronously (default).
  • queued — accepted onto the carrier-safe priority lane (the platform paces sends within per-carrier limits) and sent as soon as there is headroom. SMS uses this paced path; WhatsApp free-form sends are always synchronous. The returned message_id is the id the message is sent under, but a queued message is briefly un-queryable via GET /v1/messages/{message_id} until it dispatches (sub-second), and its conversation_id is assigned then.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Request

This endpoint expects an object.
agent_idstringRequired
channelenumRequired
Allowed values:
from_numberstringRequired
to_numberstringRequired
bodystringRequired
phone_number_idstringOptional

WhatsApp business phone number ID (required for WhatsApp channel)

message_typeenumOptionalDefaults to text
Message type. Defaults to text for SMS.
media_urlstringOptional

URL to media file (required for non-text message_type)

media_captionstringOptional
Optional caption for images and videos

Response

Message accepted. status is sent (synchronous) or queued (accepted onto the paced priority lane — delivery via message.* webhooks).

message_idstringOptional
conversation_idstringOptional
agent_idstringOptional
channelenumOptional
Allowed values:
directionenumOptional
Allowed values:
from_numberstringOptional
to_numberstringOptional
bodystringOptional
statusenumOptional
Allowed values:
segmentsintegerOptional

Number of SMS segments the message was split into. Populated for SMS channel only; null for WhatsApp.

created_atdatetimeOptional
is_sandboxbooleanOptional

True when the message was created with a pk_test_ (sandbox) API key. Omitted when false.