Set chat background

client.Chats.Background.Set(ctx, chatID, body) error

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

ParametersExpand Collapse

chatID string

formatuuid

body ChatBackgroundSetParams

Type param.Field[ChatBackgroundSetParamsType]

The background family.

const ChatBackgroundSetParamsTypeColor ChatBackgroundSetParamsType = "color"

const ChatBackgroundSetParamsTypeDynamic ChatBackgroundSetParamsType = "dynamic"

const ChatBackgroundSetParamsTypePhoto ChatBackgroundSetParamsType = "photo"

ImageURL param.Field[string]Optional

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.

formaturi

maxLength2048

Shades param.Field[[]string]Optional

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 param.Field[ChatBackgroundSetParamsStyle]Optional

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

const ChatBackgroundSetParamsStyleSky ChatBackgroundSetParamsStyle = "sky"

const ChatBackgroundSetParamsStyleWater ChatBackgroundSetParamsStyle = "water"

const ChatBackgroundSetParamsStyleAurora ChatBackgroundSetParamsStyle = "aurora"

Variant param.Field[string]Optional

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.

Set chat background

package main

import (
  "context"

  "github.com/linq-team/linq-go"
  "github.com/linq-team/linq-go/option"
)

func main() {
  client := linqgo.NewClient(
    option.WithAPIKey("My API Key"),
  )
  err := client.Chats.Background.Set(
    context.TODO(),
    "550e8400-e29b-41d4-a716-446655440000",
    linqgo.ChatBackgroundSetParams{
      Type: linqgo.ChatBackgroundSetParamsTypeColor,
      Variant: linqgo.String("mango"),
    },
  )
  if err != nil {
    panic(err.Error())
  }
}

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