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