## Set chat background

**post** `/v3/chats/{chatId}/background`

Set the transcript background for a chat.

Provide one of: a **color** (a named preset or a custom 2-stop gradient),
a **dynamic** animated style, or a **photo** (by URL). The request is accepted
asynchronously; the terminal result arrives via the `chat.background_updated`
webhook on success, or `chat.background_update_failed` on failure.

**Group chats are supported.** Requests for RCS or SMS chats are accepted (`202`)
but no background is applied and no `chat.background_updated` webhook fires.

### Path Parameters

- `chatId: string`

### Body Parameters

- `type: "color" or "dynamic" or "photo"`

  The background family.

  - `"color"`

  - `"dynamic"`

  - `"photo"`

- `image_url: optional string`

  Photo: the image URL to embed in the background. Must be an absolute `https`
  URL pointing at an image (`.jpg`, `.png`, `.heic`, `.webp`), and the image is
  fetched and re-hosted on our CDN before the request is accepted — the same way
  `group_chat_icon` works. A URL we cannot fetch, or one that isn't an image, is
  rejected with a `400` (`5007`/`5006`) rather than failing later on the device.

  Example: `https://cdn.linqapp.com/u/bg.jpg`.

- `shades: optional array of string`

  Color with `variant: custom`: the two gradient stops as hex, top then bottom —
  e.g. `["#F2C4E1", "#F5A623"]`. Ignored for named color variants (they carry
  their own two colors).

- `style: optional "sky" or "water" or "aurora"`

  Dynamic: the animated style — `sky`, `water`, or `aurora`.

  - `"sky"`

  - `"water"`

  - `"aurora"`

- `variant: optional string`

  Color: a named swatch — `mango`, `ice`, `plum`, `deep_sea`, `green_apple`,
  `cherry`, `bubblegum`, `tangerine`, `magenta`, `lime`, `silver`, `carbon`,
  `stone` — or `custom` (supply `shades`). Omitting `variant` is equivalent to
  `custom`, so it still requires `shades`.

  Dynamic: required — the variant within the `style`. `sky`: `dusk`, `haze`,
  `sunset`, `clear`, `sunrise`, `dawn`. `water`: `light`, `dark`. `aurora`:
  `green`, `purple`, `pink`.

  An unrecognized value is rejected with `400`.

### Example

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

#### Response

```json
{
  "error": {
    "status": 400,
    "code": 1002,
    "message": "Phone number must be in E.164 format",
    "doc_url": "https://docs.linqapp.com/error/codes/1xxx/1002/"
  },
  "success": false
}
```