Apple introduced conversation background customization in iMessage with iOS 26. Today, Spectrum takes it a step further with a new API that allows developers to programmatically personalize iMessage backgrounds for each conversation.

We’ve seen thousands of agents built with Spectrum, but visually, they’ve all looked the same. This new API unlocks a completely new layer of identity, giving every agent its own immersive visual presence inside each user’s conversation.

Send a background update

The main form is space.send(...).

import { background } from "spectrum-ts/providers/imessage";

await space.send(background("./wallpaper.jpg"));

import { background } from "spectrum-ts/providers/imessage";

await space.send(background("./wallpaper.jpg"));

import { background } from "spectrum-ts/providers/imessage";

await space.send(background("./wallpaper.jpg"));

This sets wallpaper.jpg as the background for the iMessage conversation.

When you pass a file path, Spectrum reads the MIME type from the file extension. For most use cases, that is all you need.

If your agent already has an image in memory, pass a buffer and include the MIME type.

await space.send(background(buffer, {
	mimeType: "image/jpeg",
}));

await space.send(background(buffer, {
	mimeType: "image/jpeg",
}));

await space.send(background(buffer, {
	mimeType: "image/jpeg",
}));

This works well when your agent generates an image, downloads one, or receives one from another service before applying it to the conversation.

Clear the background

Your agent can also return the conversation to the default iMessage background.

await space.send(background("clear"));

await space.send(background("clear"));

await space.send(background("clear"));

"clear" is reserved for this behavior. If you have a real file named clear with no extension, pass it as ./clear or load it as a buffer.

Use .background as developer sugar

We prioritize the space.send(...) format because it matches how Spectrum works: your agent sends an action into the conversation.

For human developer ergonomics, we also provide .background(...) as sugar.

import { imessage } from "spectrum-ts/providers/imessage";

const im = imessage(space);

await im.background("./wallpaper.jpg");
await im.background("clear");

import { imessage } from "spectrum-ts/providers/imessage";

const im = imessage(space);

await im.background("./wallpaper.jpg");
await im.background("clear");

import { imessage } from "spectrum-ts/providers/imessage";

const im = imessage(space);

await im.background("./wallpaper.jpg");
await im.background("clear");

It does the same thing. Use whichever form feels cleaner in your code.

What happens after the call returns

After a successful update, the background usually syncs to other people’s devices within about 30 seconds.

Spectrum waits until the background image is ready to distribute. Then the conversation accepts the background change, and iCloud sends the image to the other people in the chat.

The call returning does not mean every device has already updated. Network state, iCloud state, and Messages state can all affect when the background appears.

If someone does not see it right away, wait a moment. Reopening Messages can help.

Limits

Chat backgrounds require cloud mode.

Apple’s Messages UI may also not show the background to every person in every case. For example, if someone in a group has never spoken in the conversation or is treated as unknown by the system, Messages may not show the background to that person until they interact with the group or mark the sender as known.

That is a Messages behavior. It is not a Spectrum bug.

Built for agents that feel native

Most legacy iMessage API providers stop at message delivery.

Spectrum is built for a different kind of agent experience. If an agent is going to live inside iMessage, it should feel like it belongs there. It should support the details that make conversations feel natural: replies, reactions, groups, attachments, and now backgrounds.

This is why agent companies with taste choose Spectrum. They are not just looking for a way to send messages. They are building agents people actually want to talk to.

Try it

Read the docs here:

Chat backgrounds in Spectrum

Apple’s guide for the user-facing feature is here:

Add backgrounds in Messages on iPhone

If your agent already has an iMessage space, the whole thing is one line.

await space.send(background("./wallpaper.jpg"));

await space.send(background("./wallpaper.jpg"));

await space.send(background("./wallpaper.jpg"));

One small API. A more personal conversation. A more native-feeling agent.