> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trychert.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Backgrounds

> Set, check, and clear a conversation background.

Change the background of an existing iMessage conversation using your own image.
The change comes from the chat's pinned sender line.

> [!NOTE]
>
> 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](https://docs.trychert.com/api/sending.md). The chat must
already have a pinned sender line. Authenticate with a bearer token or HMAC as
described in [Authentication](https://docs.trychert.com/api/authentication.md).

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

```json theme={null}
{
  "image_base64": "BASE64_IMAGE",
  "mime_type": "image/png"
}
```

```bash cURL theme={null}
curl -X PUT "https://console.trychert.com/api/v1/chats/$CHAT_ID/background" \
  -H "Authorization: Bearer $CHERT_SIGNING_SECRET" \
  -H "x-chert-tenant: $TENANT" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: background-set-001" \
  --data-binary @background.json
```

```js Node.js theme={null}
import { readFile } from "node:fs/promises"

const response = await fetch(
  `https://console.trychert.com/api/v1/chats/${process.env.CHAT_ID}/background`,
  {
    method: "PUT",
    headers: {
      Authorization: `Bearer ${process.env.CHERT_SIGNING_SECRET}`,
      "x-chert-tenant": process.env.TENANT,
      "Content-Type": "application/json",
      "Idempotency-Key": "background-set-001"
    },
    body: await readFile("background.json", "utf8")
  }
)
const result = await response.json()
console.log(response.status, result)
```

```python Python theme={null}
import os
from pathlib import Path
import requests

response = requests.put(
    f"https://console.trychert.com/api/v1/chats/{os.environ['CHAT_ID']}/background",
    headers={
        "Authorization": f"Bearer {os.environ['CHERT_SIGNING_SECRET']}",
        "x-chert-tenant": os.environ["TENANT"],
        "Content-Type": "application/json",
        "Idempotency-Key": "background-set-001",
    },
    data=Path("background.json").read_bytes(),
    timeout=40,
)
print(response.status_code, response.json())
```

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.

```json 202 Accepted theme={null}
{
  "chat_id": "YOUR_CHAT_ID",
  "status": "invoked_unconfirmed",
  "operation_id": "bg_0123456789abcdef0123456789abcdef",
  "transfer_id": "8ca65c75-3283-4fb6-94ab-5cbd83d12520",
  "replayed": false,
  "recipient_confirmed": false,
  "retryable": false
}
```

| Field | Meaning |
| - | - |
| `operation_id` | Identifies the recorded background operation. |
| `transfer_id` | Identifies its image or clear transfer. It is not a delivery receipt. |
| `replayed` | Whether this is the recorded result of an earlier identical request. |
| `recipient_confirmed` | Remains false because the API does not confirm recipient display. |
| `retryable` | Remains false. Do not automatically send another change. |

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.

```bash theme={null}
curl "https://console.trychert.com/api/v1/chats/$CHAT_ID/background" \
  -H "Authorization: Bearer $CHERT_SIGNING_SECRET" \
  -H "x-chert-tenant: $TENANT"
```

```json 200 OK theme={null}
{
  "chat_id": "YOUR_CHAT_ID",
  "has_background": true,
  "observation": "local_only",
  "recipient_confirmed": false
}
```

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

```bash theme={null}
curl -X DELETE "https://console.trychert.com/api/v1/chats/$CHAT_ID/background" \
  -H "Authorization: Bearer $CHERT_SIGNING_SECRET" \
  -H "x-chert-tenant: $TENANT" \
  -H "Idempotency-Key: background-clear-001"
```

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

| HTTP | Code | When |
| - | - | - |
| 400 | `1001`, `1002`, `1004` | Missing or invalid input, malformed JSON, or an invalid idempotency key. |
| 403 | `2005` | The request is not authorized for the chat's project. |
| 404 | `2002` | The chat was not found for your tenant. |
| 409 | `1002` | The idempotency key conflicts with an earlier request. |
| 422 | `4099` | The chat is ineligible or the operation could not start. |
| 501 | `4099` | Background changing is unavailable on the selected line. |
| 502 | `4001` | The operation failed or its outcome remains unconfirmed. |
| 503 | `3002` | The selected line or chat lookup is unavailable. |

Check `error.retryable` and retain the original key when reconciling a request.
See [Errors](https://docs.trychert.com/api/errors.md) for the shared error envelope and authentication errors.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.