iMessage chat backgrounds API
On iOS 26 either side of a conversation can set a background picture. Send POST /api/imessage/background with a preset or your own image, and your webhook gets background.changed when they change theirs.
Pro is $49/month per number. Limits apply to every send.
{"to": "+18055559876", "preset": "aurora"}
Pick a background and send it.
Four presets are ready to send, or send your own picture. Applying or removing a background changes it for both people in that conversation.
Their background changes reach your server.
When they set or remove theirs, your webhook gets background.changed. It never arrives as message.received, so an auto-responder stays quiet.
Or send your own picture.
Send a JPEG, PNG, WebP, HEIC, GIF, TIFF or BMP up to 5 MiB. We center it and crop it to 1125 by 2436.

A background is not a message.
It does not count against your limits, and nothing answers it.
How it works
- Start from a conversation. A background needs an existing conversation with that person. A number cannot open a new one with it.
- Send the call.
POST /api/imessage/backgroundwithtoand exactly one ofpreset,image_b64,archive_b64orremove: true. The reply hasok, anidand the storedrecord. - Hear about theirs. When they change their background, your webhook gets
background.changed.GET /api/imessage/background?handle=returns the latest one for a conversation.
POST /api/imessage/background
{"to": "+18055559876", "preset": "aurora"}
// your own picture
{"to": "+18055559876", "image_b64": "<base64>"}
// take it away
{"to": "+18055559876", "remove": true}
// when they change theirs, your webhook gets
{"event": "background.changed",
"message": {"kind": "background", "direction": "in",
"background": {"action": "changed",
"image": {...}}}}
Calls and events
| Call or event | What it does |
|---|---|
POST /api/imessage/background | Sets a preset or your own image, or removes the background. It does not count as a message or a new contact. |
POST /api/imessage/background/prepare | Returns a preview of your image as a 1125 by 2436 JPEG. It changes no conversation and stores nothing. |
GET /api/imessage/background | Returns the latest known background for a conversation, or {"record": null} when none is stored. Add line or line_id to pick a number. |
background.changed | They set, changed or removed theirs, or a change you sent went out. background.action is changed or removed. |
background.failed | A change you sent did not reach their phone. The record is stored with status failed. |
| MCP tools | list_background_presets browses the catalog. set_chat_background sets or removes one, with the same checks as REST. |
Limits and plans
iOS 26
Backgrounds are an iOS 26 feature. Only people on iOS 26 or later can set or see one.
409 no_conversation
There are no earlier messages with this person. A background cannot open a conversation.
409 background_unsupported
Chat backgrounds are unavailable on this line until it is updated.
422 invalid_request
An unknown preset name, or more than one of <code>preset</code>, <code>image_b64</code>, <code>archive_b64</code> and <code>remove</code>.
503 background_unavailable
A bundled preset is missing or damaged, or a preview is busy. Nothing was sent to the phone.
Your own image
JPEG, PNG, WebP, HEIC, GIF, TIFF or BMP, up to 5 MiB and 40 megapixels. An animated image uses its first frame. We apply the EXIF orientation, place transparent pixels on white and strip the metadata.
Archives
<code>archive_b64</code> takes a prebuilt transcript-background archive of up to 8 MiB before base64. A regular photo ZIP does not work.
What success means
It means the transport accepted the change. It does not confirm that their phone displayed it.
Not a message
It counts toward no usage and no conversation count, and it is not a new contact. The hosted AI agent does not answer it, and you cannot react or reply to it.
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 chat background API?
Yes. POST /api/imessage/background sets or removes the background of a conversation. Send to and exactly one of preset, image_b64, archive_b64 or remove: true. On iOS 26 the picture shows for both people in that conversation.
How do I set a chat background from code?
Send POST /api/imessage/background with to and a preset such as aurora, or an image_b64 of your own. The conversation has to exist already. A number cannot open a new one with a background, and the send answers 409 no_conversation.
Which presets are there?
Four: aurora (emerald and violet light), sorbet (peach and coral waves), lagoon (turquoise water) and bloom (rose and lilac petals). The public catalog is at /assets/chat-backgrounds/manifest.json. Over MCP, list_background_presets returns the same list.
How do I know when someone changes the background?
Your webhook gets background.changed, never message.received, so an auto-responder does not answer it. The message is a record with kind: "background" and an action of changed or removed. GET /api/imessage/background returns the latest one.
Does a background count as a message or a new contact?
No. It counts toward no usage and no conversation count, and it is not a new contact. The hosted AI agent does not answer it, a connected CRM does not log it, and you cannot react or reply to it.
Can I use my own image?
Yes. Send image_b64 as a JPEG, PNG, WebP, HEIC, GIF, TIFF or BMP, up to 5 MiB and 40 megapixels. We center and crop it to 1125 by 2436. POST /api/imessage/background/prepare returns a preview first and changes nothing.
Does a successful send mean they see the background?
No. Success means the transport accepted the change. It does not confirm that their phone displayed it. A change that does not reach their phone is stored as failed and arrives as background.failed.
Set your first background
Get a number, text someone, then send POST /api/imessage/background with a preset.