Chat Backgrounds

Chats

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

Set a background

cURL

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.

Remove a background

cURL

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.

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.

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 for the payload schema and Webhooks 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.

Group Chats — backgrounds work here too
Webhook Events — the chat.background_updated payload