iMessage chat backgrounds

Set or clear the chat background image. Import background from the iMessage provider and use the sugar method on a narrowed space:

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

const im = imessage(space);

// Set from a file path - MIME type inferred from the extension
await im.background("./wallpaper.jpg");

// Set from a buffer - mimeType is required
await im.background(buffer, { mimeType: "image/jpeg" });

// Clear the current background
await im.background("clear");

space.background(...) is sugar for space.send(background(...)). The canonical form works on any space reference:

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

After a successful set, the background usually syncs to other users’ devices within 30s. The background asset is uploaded to iCloud and then distributed to the other members of the conversation. Display time is not a hard SLA: network state, iCloud state, and the Messages client state can all affect when the UI appears.

Stage	What happens
Before `background(...)` resolves	The provider waits until the background asset reaches a distributable state.
After `background(...)` resolves	The conversation has accepted the background change; iCloud distributes the asset to other members.
Other members’ devices	The background appears after the device receives the iCloud distribution.

Background UI may not appear in these cases:

Case	Result
The recipient’s network, iCloud, or Messages state is unhealthy	The background may appear late, often after reopening Messages.
A group member has never spoken, interacted, or is treated by the system as unknown or untrusted	Apple may not show the background UI to that member.

The second case is an Apple Messages display limit, not a Spectrum option. If one group member never sees the background, have that member send a message in the group, mark the sender as known, or reopen Messages before retrying the background change.

Chat backgrounds require @spectrum-ts/imessage. With @spectrum-ts/imessage-local, background() throws an .

The string "clear" is a reserved sentinel. If you have a file literally named clear with no extension, pass "./clear" or load it as a Buffer.

Get started

Core concepts

Content

Providers

Advanced

Integrations

Best Practices

Troubleshooting

iMessage chat backgrounds