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.
It just came out of the oven.

Fresh this morning.

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.
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.
Photos wait for their first reply.
Photos, voice memos and videos go only to someone who has replied to this number.
- You textWant a photo of the cake?
A first message to someone new is text.
- You attach too earlyPhoto 403 attachment_before_reply
The send is refused. Nothing is sent or stored.
- They replyYes please
From then on photos, voice memos and videos go through.
How it works
- Send the file.
POST /api/imessage/sendwithtoand one ofimage_b64,audio_b64or avideo_id. A photo or video can carrytextas its caption. A voice memo cannot. - 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.
- Theirs arrive with a link.
message.receivedcarries animage,audioorvideoobject with a URL. Fetch it with your API key from/api/imessage/messages/{id}/image,/audioor/video.
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
kind, not on text.Sizes and formats
| Type | Size | Formats | Notes |
|---|---|---|---|
| Photo | 5 MB | JPEG, PNG, GIF, HEIC, WebP, TIFF, BMP | Send image_b64. An optional text is the caption, in the same bubble. |
| Voice memo | 6 MB | m4a, mp3, wav, aiff, caf, flac, aac, mp4, amr | Send audio_b64 and, if you know it, audio_format. No caption. |
| Video | Up to a minute | MP4, MOV or WebM | Uses 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.