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.

Harbor Dental
Do you have anything Thursday?
Yes, 10:30 or 2:00.

{"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.

Your server
// waiting for a change
Harbor Dental
Your cleaning is Friday at 3.
Reply here if anything changes.

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 landscape photo of a pastry on a plate, with a tall frame marking the part that is kept
Your image
1125 by 2436

A background is not a message.

It does not count against your limits, and nothing answers it.

0messages counted
0new contacts
No replyfrom the hosted AI agent
No entryin a connected CRM

How it works

  1. Start from a conversation. A background needs an existing conversation with that person. A number cannot open a new one with it.
  2. Send the call. POST /api/imessage/background with to and exactly one of preset, image_b64, archive_b64 or remove: true. The reply has ok, an id and the stored record.
  3. 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.
Set, remove, receive
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": {...}}}}
The presets are aurora, sorbet, lagoon and bloom. The full reference is in our docs.

Calls and events

Chat background calls and webhook events
Call or eventWhat it does
POST /api/imessage/backgroundSets 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/prepareReturns a preview of your image as a 1125 by 2436 JPEG. It changes no conversation and stores nothing.
GET /api/imessage/backgroundReturns the latest known background for a conversation, or {"record": null} when none is stored. Add line or line_id to pick a number.
background.changedThey set, changed or removed theirs, or a change you sent went out. background.action is changed or removed.
background.failedA change you sent did not reach their phone. The record is stored with status failed.
MCP toolslist_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.