Developer guideiMessage API6 min read
iMessage API: media, files and voice notes
Send and receive images, video, documents and voice notes through an iMessage API: supported types, size limits, uploads, malware scanning and captions.
The short answer
Flow's iMessage API handles images, video, audio, documents and voice notes. Upload once, send by file ID, and let Flow check the real file type and scan documents for malware before they are kept.
Building on the iMessage API? Build on iMessage with Flow: one agent for iMessage, WhatsApp and Telegram. New to it? Read the iMessage API guide.
What you can send
An agent that only sends text misses half of what people do on iMessage. From Flow’s iMessage docs, the line supports:
| Content | iMessage |
|---|---|
| Text | Yes, up to 9,999 characters |
| Images, video, audio | Yes |
| Documents | Yes, sent and received; malware-scanned before Flow keeps them |
| Voice notes | Yes, from an mp3, wav, m4a, caf or aac file |
| Files per message | One, with an optional caption |
| Contact cards and locations | No; refused with 422 unsupported_content, so send the details as text |
Upload, then send
On Flow you upload the file first, then send it by file_id. The upload checks the real file type from the file’s first bytes, so a renamed file does not get through. Programs, web pages and unknown types are refused with 422 unsupported_content. Images, audio and video are not scanned and are taken. Documents, such as PDFs and Office files, are scanned for malware, and one that fails answers 422 file_blocked.
A media message can carry a caption of up to 1,024 characters. If your agent sends images, add a caption that explains them. Not every client shows alt text.
For the full content model, including how one handler serves other channels, see One agent on iMessage, WhatsApp and Telegram.
Receiving media
When a customer sends a photo or a document, Flow fetches it from the channel once, before the message.received event is delivered. The event links to Flow’s download endpoint, which redirects to a short-lived signed URL on a separate file domain. That means your handler does not have to race a channel’s own expiring link.
Treat inbound files as untrusted input. Check the type and size before you pass a file to a model or store it, and do not open documents from strangers in a tool with broad access. The security checklist has more.
Retention applies to files too. Message content and files are kept for your plan’s retention, 30 days by default, and a file is deleted after that. Deleting a contact deletes the files in their conversations.
Voice notes
Voice notes are common, and they work both ways. To send one, send voice content from an audio file in one of the supported formats. To receive one, you get voice content with the audio file and its duration.
On Flow’s iMessage line, the agent receives the audio file, and the transcript iMessage itself made when it made one. Flow makes no transcripts on any channel, so on WhatsApp and Telegram, and on iMessage when there is no transcript, fetch the audio and transcribe it yourself if your agent needs the words.
Limits and safety
- Size. Check the current limit for the line and channel you use before accepting large files.
- Type. Expect a refusal for anything outside images, audio, video and documents.
- Scanning. Know whether documents are scanned. On Flow they are.
- Captions. Keep them within 1,024 characters.
- Unsupported kinds. Flow converts nothing. When a channel does not take something, Flow refuses it with
422 unsupported_contentand sends nothing, and the hint says what to send instead. - Retention. Files are not kept forever. Store what you need yourself.
Send iMessage programmatically shows the send call and the errors to handle.
Frequently asked questions
Can an iMessage API send images and video?
Yes. Flow's iMessage line supports images, video, audio and documents, plus voice notes. Upload media through the files endpoint, then send it by file ID or from the documented content object.
What audio formats work for voice notes?
On Flow's iMessage line, voice notes are sent from an mp3, wav, m4a, caf or aac file. A received voice note arrives as the audio file, with the transcript iMessage itself made when it made one. Flow makes no transcripts.
Are uploaded files scanned?
On Flow, documents such as PDFs and Office files are scanned for malware before Flow keeps them, and a file that fails answers 422 file_blocked. Images, audio and video are not scanned and are taken.
How long is a caption allowed to be?
A media caption takes at most 1,024 characters on Flow, also when an edit replaces it. Text messages on iMessage can be up to 9,999 characters.
Does the API check the file type?
Yes. Flow checks the real type from the file's first bytes. Programs, web pages and unknown types are refused with 422 unsupported_content.
How do I read a file a customer sent?
Inbound media is fetched from the channel once, before its event is delivered, and event payloads link to Flow's download endpoint, which redirects to a short-lived signed URL.
Keep reading
All posts: the Flow blog. The Flow docs have the reference.
From reading to building
Your agent, on iMessage and everywhere else.
Flow gives your agent an iMessage line, and the same code answers on WhatsApp and Telegram and works as an MCP server and CLI. See how it works on iMessage.
Build on iMessage with Flow