iMessage photos and voice memos API

Send a photo with image_b64 or a voice memo with audio_b64 on POST /api/imessage/send. When people send you one, message.received carries a link to the file.

Pro is $49/month per number. Limits apply to every send.

Flour Pot Bakery
Can I see the cake?
A strawberry pastry on a dark plate

Fresh this morning.

{"to": "+18055559876", "image_b64": "...", "text": "Fresh this morning."}

A photo and its caption, in one bubble.

A photo arrives as a photo with its caption inside the same bubble. A voice message and a video arrive as the bubbles Messages draws.

Voice memos keep their waveform.

The recipient gets a play button, a waveform and a transcript their phone makes. Text-to-speech output in mp3, wav or m4a goes straight in.

0:07

Hi, it is Flour Pot Bakery. Your order is ready for pickup.

{"to": "+18055559876", "audio_b64": "...", "audio_format": "m4a"}

Their photos come to your server.

A photo, voice memo or video they send arrives as message.received with a link. Fetch the file with your API key.

Your server
// waiting for a message

Photos wait for their first reply.

Photos, voice memos and videos go only to someone who has replied to this number.

  1. You text
    Want a photo of the cake?

    A first message to someone new is text.

  2. You attach too early
    Photo 403 attachment_before_reply

    The send is refused. Nothing is sent or stored.

  3. They reply
    Yes please

    From then on photos, voice memos and videos go through.

How it works

  1. Send the file. POST /api/imessage/send with to and one of image_b64, audio_b64 or a video_id. A photo or video can carry text as its caption. A voice memo cannot.
  2. They see a native bubble. A photo shows with its caption in the same bubble. A voice memo shows a waveform, a play button and the transcript their phone makes. A video shows as a native video bubble.
  3. Theirs arrive with a link. message.received carries an image, audio or video object with a URL. Fetch it with your API key from /api/imessage/messages/{id}/image, /audio or /video.
Send, receive, fetch
POST /api/imessage/send
{"to": "+18055559876", "image_b64": "<base64>",
 "image_format": "jpg", "text": "Fresh this morning."}

// a voice memo
{"to": "+18055559876", "audio_b64": "<base64>",
 "audio_format": "m4a"}

// when they send you one, your webhook gets
{"event": "message.received",
 "message": {"kind": "image",
             "image": {"url": "/api/imessage/messages/45/image", ...}}}

GET /api/imessage/messages/45/image
Authorization: Bearer YOUR_TOKEN
The full reference is in our docs. A photo without a caption and a voice memo store placeholder text, so branch on kind, not on text.

Sizes and formats

Attachment sizes, formats and notes
TypeSizeFormatsNotes
Photo5 MBJPEG, PNG, GIF, HEIC, WebP, TIFF, BMPSend image_b64. An optional text is the caption, in the same bubble.
Voice memo6 MBm4a, mp3, wav, aiff, caf, flac, aac, mp4, amrSend audio_b64 and, if you know it, audio_format. No caption.
VideoUp to a minuteMP4, MOV or WebMUses credits, 1 for every 3 MB. M4V, 3GP and MKV work too. Other containers return 422 video_invalid.

Limits and plans

403 attachment_before_reply

A photo, video, voice memo or poll to someone who has never replied to this number. Text them first. Nothing was sent or stored.

No caption on a voice memo

Send <code>text</code> or <code>audio_b64</code>, never both. Send the words as a second message.

No reply with a voice memo

A voice memo cannot be an inline reply. The send answers <code>422 invalid_request</code>.

Metadata

We remove photo metadata such as GPS when we re-encode a file. A JPEG we pass through as sent keeps whatever you put in it, so strip it yourself if it matters.

What you receive

A HEIC photo from an Apple phone arrives as JPEG. A Live Photo arrives as its still. A voice memo arrives as an <code>.m4a</code> with its length filled in.

Reactions

Tapbacks work on a photo, voice memo or video like on any message. See iMessage reactions.

Plans

Pro is $49/month per number, with 5 new contacts a day per number. Growth has 25+ new contacts a day per number. Details are on the iMessage API page.

Questions

Is there an iMessage photos API?

Yes. POST /api/imessage/send with image_b64 sends a photo of up to 5 MB as a native photo bubble. An optional text is the caption, in the same bubble. JPEG, PNG, GIF, HEIC, WebP, TIFF and BMP are accepted.

How do I send a voice message over iMessage from code?

Pass audio_b64 instead of text to POST /api/imessage/send, up to 6 MB, with an optional audio_format such as m4a. It arrives as the native audio bubble with a waveform, a play button and the transcript their phone generates.

Can I add a caption to a voice message?

No. Messages has no caption on a voice bubble, so send words as a second message. A photo is different: its caption sits in the same bubble.

How do I receive photos and voice messages?

Your webhook gets message.received with an image, audio or video object that holds a URL. Fetch the file with your API key from /api/imessage/messages/{id}/image, /audio or /video. A HEIC photo arrives as JPEG, and a voice message arrives as an .m4a.

Why did my photo return 403 attachment_before_reply?

Photos, voice messages, videos and polls go only to someone who has replied to this number. Text them first. Nothing was sent or stored for the refused call.

Can I send text-to-speech as a voice message?

Yes. The mp3, wav or m4a from a text-to-speech API goes straight into audio_b64. Under a minute lands, and two or three sentences land best.

Do photos and voice messages cost extra?

No. There is no per-message charge for photos or voice messages. Videos use credits, 1 for every 3 MB.

Send your first photo

Get a number, wait for the first reply, then send POST /api/imessage/send with image_b64.