Chat Backgrounds

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.

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.

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.

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

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

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.

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.

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.

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.

• 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