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 ParametersExpand Collapse

chatId: string

formatuuid

Body ParametersJSONExpand Collapse

type: "color" or "dynamic" or "photo"

The background family.

One of the following:

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

One of the following:

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

Set chat background

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"
        }'

{
  "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
}

{
  "error": {
    "status": 401,
    "code": 2004,
    "message": "Unauthorized - missing or invalid authentication token",
    "doc_url": "https://docs.linqapp.com/error/codes/2xxx/2004/"
  },
  "success": false
}

{
  "error": {
    "status": 403,
    "code": 2005,
    "message": "Access denied - insufficient permissions for this resource",
    "doc_url": "https://docs.linqapp.com/error/codes/2xxx/2005/"
  },
  "success": false
}

{
  "error": {
    "status": 404,
    "code": 2001,
    "message": "Resource not found",
    "doc_url": "https://docs.linqapp.com/error/codes/2xxx/2001/"
  },
  "success": false
}

{
  "error": {
    "status": 500,
    "code": 3006,
    "message": "Internal server error",
    "doc_url": "https://docs.linqapp.com/error/codes/3xxx/3006/"
  },
  "success": false
}

Returns Examples

{
  "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
}

{
  "error": {
    "status": 401,
    "code": 2004,
    "message": "Unauthorized - missing or invalid authentication token",
    "doc_url": "https://docs.linqapp.com/error/codes/2xxx/2004/"
  },
  "success": false
}

{
  "error": {
    "status": 403,
    "code": 2005,
    "message": "Access denied - insufficient permissions for this resource",
    "doc_url": "https://docs.linqapp.com/error/codes/2xxx/2005/"
  },
  "success": false
}

{
  "error": {
    "status": 404,
    "code": 2001,
    "message": "Resource not found",
    "doc_url": "https://docs.linqapp.com/error/codes/2xxx/2001/"
  },
  "success": false
}

{
  "error": {
    "status": 500,
    "code": 3006,
    "message": "Internal server error",
    "doc_url": "https://docs.linqapp.com/error/codes/3xxx/3006/"
  },
  "success": false
}