# Background

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

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

- `shades: optional array of 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: optional "sky" or "water" or "aurora" or "glitter"`

  Dynamic: the animated style.

  - `"sky"`

  - `"water"`

  - `"aurora"`

  - `"glitter"`

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

### 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",
          "image_url": "https://cdn.linqapp.com/u/bg.jpg",
          "shades": [
            "#F2C4E1",
            "#F5A623"
          ],
          "style": "sky",
          "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
}
```

## Remove chat background

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

Remove the transcript background from a chat, resetting it to the default.

### Path Parameters

- `chatId: string`

### Example

```http
curl https://api.linqapp.com/api/partner/v3/chats/$CHAT_ID/background \
    -X DELETE \
    -H "Authorization: Bearer $LINQ_API_V3_API_KEY"
```

#### 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
}
```