---
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-34)
- [TypeScript](#tab-panel-35)
- [Python](#tab-panel-36)
- [Go](#tab-panel-37)

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"
    }'
```

```
await client.chats.background.set({chatId}, {
  type: "color",
  variant: "mango",
});
```

```
client.chats.background.set(
    {chat_id},
    type="color",
    variant="mango",
)
```

```
client.Chats.Background.Set(context.TODO(), {chatId}, linq.ChatBackgroundSetParams{
  Type: linq.F("color"),
  Variant: linq.F("mango"),
})
```

`type` picks one of three families, and each one takes its own fields. Send the fields for one family only — anything belonging to another is ignored.

### Color

A named swatch, by `variant`:

```
{ "type": "color", "variant": "mango" }
```

The swatches are `mango`, `ice`, `plum`, `deep_sea`, `green_apple`, `cherry`, `bubblegum`, `tangerine`, `magenta`, `lime`, `silver`, `carbon`, `stone`.

Or your own gradient, with `variant: custom` and exactly two hex `shades` — top stop first:

```
{ "type": "color", "variant": "custom", "shades": ["#F2C4E1", "#F5A623"] }
```

`shades` only applies to `custom`; named swatches carry their own two colors. Omitting `variant` is the same as `custom`, so it still needs `shades`.

### Dynamic

An animated background, as a `style` plus a `variant` within it — both required:

```
{ "type": "dynamic", "style": "water", "variant": "dark" }
```

| `style`  | `variant`                                            |
| -------- | ---------------------------------------------------- |
| `sky`    | `dusk`, `haze`, `sunset`, `clear`, `sunrise`, `dawn` |
| `water`  | `light`, `dark`                                      |
| `aurora` | `green`, `purple`, `pink`                            |

### Photo

Your own image, from an `https` URL we can fetch:

```
{ "type": "photo", "image_url": "https://cdn.linqapp.com/u/bg.jpg" }
```

We download the image and re-host it on our CDN before accepting the request, so a URL we can’t fetch — or one that isn’t an image — fails here with a `400` rather than later on the device.

A `variant` or `style` outside the lists above is likewise rejected with a `400`, not accepted and silently dropped.

Every field is listed in the [Set Background API reference](/api/resources/chats/subresources/background/methods/set/index.md).

## Remove a background

- [cURL](#tab-panel-38)
- [TypeScript](#tab-panel-39)
- [Python](#tab-panel-40)
- [Go](#tab-panel-41)

Terminal window

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

```
await client.chats.background.remove({chatId});
```

```
client.chats.background.remove({chat_id})
```

```
client.Chats.Background.Remove(context.TODO(), {chatId})
```

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`, or on `chat.background_update_failed` with an `error_code`. Time out rather than wait forever: a request that exhausts its internal retries fires neither.

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