Chats

Set chat 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.

post/v3/chats/{chatId}/background

Request

  • Base URL: https://api.linqapp.com/api/partner
  • URL: https://api.linqapp.com/api/partner/v3/chats/{chatId}/background
  • Auth: HTTP bearer

Path parameters

chatIdstring uuid required
Example:550e8400-e29b-41d4-a716-446655440000

Unique identifier of the chat

Request body

type'color' | 'dynamic' | 'photo' required

The background family.

variantstring

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.

shadesstring[]

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'sky' | 'water' | 'aurora'

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

image_urlstring uri

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.

Example request

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

Response

Request accepted for processing. Result arrives via chat.background_updated or chat.background_update_failed.

Changes

No recorded changes to this operation across all 1 revision of this API.