---
title: Chat Backgrounds | API Docs
description: Set a color, animated, or photo background on a chat transcript.
---

A chat background is the wallpaper behind a conversation’s transcript. Setting one changes what **both sides** see in that chat — it is a property of the conversation, not a local display preference.

Backgrounds are an iMessage feature and work in one-to-one and [group chats](/guides/chats/group-chats/index.md) alike.

## Set a background

- [cURL](#tab-panel-26)

Terminal window

```
curl -X POST https://api.linqapp.com/api/partner/v3/chats/{chatId}/background \
  -H "Authorization: Bearer $LINQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "type": "color",
      "variant": "mango"
    }'
```

| Field       | Required | Type                                | Description                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| ----------- | -------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`      | Yes      | `color \| dynamic \| photo`         | The background family.                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `variant`   | No       | `string`                            | Color: a named swatch — \`mango\`, \`ice\`, \`plum\`, \`deep\_sea\`, \`green\_apple\`, \`cherry\`, \`bubblegum\`, \`tangerine\`, \`magenta\`, \`lime\`, \`silver\`, \`carbon\`, \`stone\` — or \`custom\` (supply \`shades\`). Dynamic: the variant within the \`style\` (e.g. \`sunrise\`). An unrecognized value still returns \`202\`, but no background is applied and no \`chat.background\_updated\` webhook fires. Send one of the values above. |
| `shades`    | No       | `array<string>`                     | Color with \`variant: custom\`: the two gradient stops as hex, top then bottom. Ignored for named color variants (they carry their own two colors).                                                                                                                                                                                                                                                                                                     |
| `style`     | No       | `sky \| water \| aurora \| glitter` | Dynamic: the animated style.                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `image_url` | No       | `string`                            | Photo: the image URL to embed in the background.                                                                                                                                                                                                                                                                                                                                                                                                        |

Pick one of three families with `type`, then supply that family’s fields:

| `type`    | What you supply                                                             |
| --------- | --------------------------------------------------------------------------- |
| `color`   | `variant` — a named swatch, or `custom` with two hex `shades` (top, bottom) |
| `dynamic` | `style` — an animated style, plus an optional `variant` within it           |
| `photo`   | `image_url` — a publicly reachable image                                    |

Named color swatches carry their own two colors, so `shades` is ignored unless `variant` is `custom`. The animated styles are `sky`, `water`, `aurora`, `glitter`.

An unrecognized `variant` still returns `202`, but no background is applied and no webhook fires. Send one of the documented values.

See the [Set Background API reference](/api/resources/chats/subresources/background/methods/set/index.md).

## Remove a background

- [cURL](#tab-panel-25)

Terminal window

```
curl -X DELETE https://api.linqapp.com/api/partner/v3/chats/{chatId}/background \
  -H "Authorization: Bearer $LINQ_API_KEY"
```

Resets the chat to the default background. See the [Remove Background API reference](/api/resources/chats/subresources/background/methods/remove/index.md).

## Confirming the change

Both endpoints return `202` — the request was accepted, not applied. The terminal result arrives on the `chat.background_updated` webhook, which carries the resulting `background` (`null` when removed) and an `actor_handle`.

A 202 is not a guarantee

Requests on RCS or SMS chats are accepted with a `202` as well, but no background is applied and **no webhook fires** — there is no failure event to wait for. Treat silence as “not applied” rather than “still pending”.

## Reacting to someone else’s change

The same webhook fires when a participant changes the background from their side, so a subscription sees both directions. `actor_handle.is_me` tells them apart: `true` when your own line set it, `false` when the recipient did.

That makes `chat.background_updated` the way to keep your own state in sync — a background can change without you ever calling the API.

See [Webhook Events](/guides/webhooks/events/index.md) for the payload schema and [Webhooks](/guides/webhooks/index.md) for setup.

## Important notes

- **iMessage only** — RCS and SMS chats accept the call and silently do nothing.
- **Both sides see it** — a background is conversation state, not a local setting.
- **Group chats are supported.**
- **`202` means accepted** — confirm with the webhook, and use `POST /v3/chats/{chatId}/background` again to change it.
- **Inbound changes fire the same event** — check `actor_handle.is_me` before echoing a change back.

## Related

- [Group Chats](/guides/chats/group-chats/index.md) — backgrounds work here too
- [Webhook Events](/guides/webhooks/events/index.md) — the `chat.background_updated` payload