Skip to main content
Change the background of an existing iMessage conversation using your own image. The change comes from the chat’s pinned sender line.
Background changing is enabled per line. Contact Chert to enable it before using these endpoints. This rollout supports existing one-to-one iMessage chats with phone recipients. Groups, SMS, email recipients, and automatic backgrounds on first contact are outside this rollout.
Use the chat_id returned by sending a message. The chat must already have a pinned sender line. Authenticate with a bearer token or HMAC as described in Authentication.

Set a background

PUT /api/v1/chats/{chat_id}/background Send a PNG or JPEG as base64 in image_base64. Use the encoded file bytes without a data URL prefix or line breaks. The decoded image must be at most 512 KiB, contain one frame, and have no more than 24 megapixels. Each dimension must be at most 12,000 pixels. Image URLs, HEIC, and animated images are not supported in this rollout. Images are center-cropped to 1200 by 1500 pixels with an opaque white base. Keep important content near the center. Depth, motion, and spatial effects are not included. Save the request body as background.json, replacing BASE64_IMAGE with your encoded image. The optional mime_type describes the image format.
The rollout returns HTTP 202 when the background operation has been invoked and recorded. It does not confirm that the recipient can see the image.
Some previously enabled lines return HTTP 200 with status set to set or cleared instead. These responses also do not confirm recipient display. Confirm the response contract for your line before relying on recorded replay behavior.

Check a background

GET /api/v1/chats/{chat_id}/background Send no body. An idempotency key is not required.
200 OK
has_background reports the state observed on the sender’s line. It can remain false while a change is being processed. Neither value proves what the recipient sees. Confirm on the receiving device when testing your integration.

Clear a background

DELETE /api/v1/chats/{chat_id}/background Send no body and use a new idempotency key for this deliberate change.
The rollout returns the same HTTP 202 response fields as setting a background, with new operation and transfer identifiers. Use GET to check the sender’s observed state after clearing.

Retries and replacement

For the rollout, Idempotency-Key is required on PUT and DELETE. Use 1 to 128 printable ASCII characters without spaces. Give each deliberate set, replacement, or clear its own key. Keep keys unique across background operations on a line. To reconcile an uncertain request, repeat the same operation with the same key, chat, and exact image bytes. A recorded invocation returns its original IDs with replayed set to true and does not send the change again. Reusing the key for different content or for clearing returns HTTP 409. An unconfirmed error does not prove the change was never sent. Do not retry it with a new key. Check the conversation and contact Chert if the result remains unclear. To replace an existing background deliberately, send another PUT with the new image and a new key.

Errors

Check error.retryable and retain the original key when reconciling a request. See Errors for the shared error envelope and authentication errors.