Send an audio message

Sends an audio file as a native iMessage audio message (waveform balloon with a play button on the receiver) instead of a generic file pill.

Two-step flow: upload an audio file via POST /v1/files, then pass the returned file ID as audio_message. Common formats are accepted — m4a, mp3, wav, caf, aiff. Audio is transcoded server-side, so you don’t need to pre-encode.

iMessage only — SMS lines are rejected. Some lines don’t support audio messages; sending from one of those returns 400 advanced_features_required.

Like POST /v1/messages, the contact-first restriction applies: the recipient must have messaged your line first.

Like all writes, this is asynchronous: returns a delivery ID with status: "pending". Track via GET /outbox or webhooks.

POST /v1/audio-messages

Send an audio message

cURL

curl --request POST \
  --url https://api.messages.dev/v1/audio-messages \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "from": "[phone]",
  "to": "[phone]",
  "audio_message": "file_abc123",
  "reply_to": "msg_abc123"
}
'

201

{
  "id": "<string>",
  "status": "<string>",
  "request_id": "<string>"
}

Authorizations

Authorization · string · header · required

Use an API key as a bearer token: Authorization: Bearer sk_live_...

Each key has a set of scopes that gate which endpoints it can call: messages:read, messages:write, chats:read, lines:read, reactions:read, reactions:write, typing:read, typing:write, receipts:read, receipts:write, webhooks:read, webhooks:write, outbox:read, files:read, files:write. Keys can also be restricted to a subset of lines.

Body

application/json

from · string · required

Sender line handle (phone number or Apple ID)

Example:

"[phone]"

to · string · required

Recipient phone number, Apple ID, or chat ID (cht_...)

Example:

"[phone]"

audio_message · string · required

File ID (file_...) of the uploaded audio

Example:

"file_abc123"

reply_to · string

Message ID (msg_...) or iMessage GUID to reply to

Example:

"msg_abc123"

Response

201

application/json

Outbox item created

id · string

Delivery ID (e.g. obx_abc123)

status · string

Allowed value: "pending"

request_id · string