Badges API

You can manage badges via API

Required Headers for all API endpoints

⚠️
Regional endpoints: Replace chatbackend.watchers.io with the endpoint matching your project region. See Supported Regions for details.
Region Endpoint
Europe (default) chatbackend.watchers.io
North America chatbackend.us.watchers.io
South America chatbackend.sa.watchers.io
Asia chatbackend.hk.watchers.io
Africa chatbackend.za.watchers.io

Region	Endpoint
Europe (default)	`chatbackend.watchers.io`
North America	`chatbackend.us.watchers.io`
South America	`chatbackend.sa.watchers.io`
Asia	`chatbackend.hk.watchers.io`
Africa	`chatbackend.za.watchers.io`

Parameter	Description
x-api-key	Your public API key used for the project
Authorization	Bearer token what you can get from the back office (Admin panel / Settings / Bearer tokens) for back-to-back integrations

Create new badge

POST Endpoint https://chatbackend.watchers.io/external/badge

Request payload

Parameter	Type	Required	Description
`text`	string	Yes	Text on badge. Better use not more than 10-12 characters, and also use emoji. (Not limited)
`backgroundColor`	string	Yes	HEX Color of badge
`textColor`	string	Yes	HEX Color of text
`tooltip`	string	Yes	Short description for badge. Limited to 140 characters.
`communicationPic`	string	Yes	The message image that the user will see when entering the chat when he has been assigned this badge. File size: No more than 10 MB Dimensions: At least 190×190 px
`communicationTitle`	string	Yes	The message title that the user will see when entering the chat when he has been assigned this badge. Limited to 140 characters.
`communicationText`	string	Yes	The message text that the user will see when entering the chat when he has been assigned this badge. Limited to 180 characters.
`pic`	string	No	URL of the badge image/icon.
`data`	string	No	Arbitrary data associated with the badge (stored as text).
`trigger`	object	No	Automatic badge assignment trigger configuration. See Badge Triggers for details.

CURL example

curl --location -X POST 'https://chatbackend.watchers.io/external/badge' --header 'Content-Type: application/json' --header 'Authorization: Bearer ${Bearer token from admin panel}' --header 'x-api-key: ${API KEY}' --data '{
    "text": "best",
    "backgroundColor": "#ea00fc",
    "textColor": "#000000",
    "tooltip": "5555",
    "communicationPic": null,
    "communicationText": "11111",
    "communicationTitle": "11111"
}'

Example response

{
  "id": 3,
  "text": "best",
  "backgroundColor": "#ea00fc",
  "textColor": "#000000",
  "tooltip": "5555",
  "pic": null,
  "data": null,
  "communicationPic": null,
  "communicationText": "11111",
  "communicationTitle": "11111",
  "chainId": null,
  "chainPosition": null,
  "chain": null,
  "createdAt": "2025-01-15T10:00:00.000Z",
  "updatedAt": "2025-01-15T10:00:00.000Z"
}

Update badge by id

PATCH Endpoint https://chatbackend.watchers.io/external/badge/:id

Request payload

Parameter	Type	Required	Description
`text`	string	Yes	Text on badge. Better use not more than 10-12 characters, and also use emoji. (Not limited)
`backgroundColor`	string	Yes	HEX Color of badge
`textColor`	string	Yes	HEX Color of text
`tooltip`	string	Yes	Short description for badge. Limited to 140 characters.
`communicationPic`	string	Yes	The message image that the user will see when entering the chat when he has been assigned this badge. File size: No more than 10 MB Dimensions: At least 190×190 px
`communicationTitle`	string	Yes	The message title that the user will see when entering the chat when he has been assigned this badge. Limited to 140 characters.
`communicationText`	string	Yes	The message text that the user will see when entering the chat when he has been assigned this badge. Limited to 180 characters.
`pic`	string	No	URL of the badge image/icon.
`data`	string	No	Arbitrary data associated with the badge (stored as text).
`trigger`	object	No	Automatic badge assignment trigger configuration. See Badge Triggers for details.

CURL example

curl --location -X PATCH 'https://chatbackend.watchers.io/external/badge/:id' --header 'Content-Type: application/json' --header 'Authorization: Bearer ${Bearer token from admin panel}' --header 'x-api-key: ${API KEY}' --data '{
    "text": "best100",
    "backgroundColor": "#ea00fc",
    "textColor": "#000000",
    "tooltip": "5555",
    "communicationPic": null,
    "communicationText": "11111",
    "communicationTitle": "11111"
}'

Example response

true

Get list of all badges

Query parameters

Parameter	Type	Required	Description
`limit`	number	No	Number of badges to return (default: 20)
`offset`	number	No	Number of badges to skip for pagination (default: 0)
`order`	string	No	Sort order, e.g. `id_desc`, `id_asc` (default: `id_desc`)

CURL example

curl --location 'https://chatbackend.watchers.io/external/badge?limit=10&offset=0' --header 'Content-Type: application/json' --header 'Authorization: Bearer ${Bearer token from admin panel}' --header 'x-api-key: ${API KEY}'

Example response

[
  {
    "id": 1,
    "text": "cool",
    "backgroundColor": "#ea00fc",
    "textColor": "",
    "tooltip": "5555",
    "pic": null,
    "communicationPic": null,
    "communicationText": "11111",
    "communicationTitle": "11111",
    "userCount": 1,
    "trigger": {
      "id": null,
      "firstMessage": null,
      "messageCount": null
    }
  }
]

Get badge by id

CURL example

curl --location 'https://chatbackend.watchers.io/external/badge/:id' --header 'Content-Type: application/json' --header 'Authorization: Bearer ${Bearer token from admin panel}' --header 'x-api-key: ${API KEY}'

Example response

{
  "id": 1,
  "text": "cool",
  "backgroundColor": "#ea00fc",
  "textColor": "",
  "tooltip": "5555",
  "pic": null,
  "data": null,
  "communicationPic": null,
  "communicationText": "11111",
  "communicationTitle": "11111",
  "chainId": null,
  "chainPosition": null,
  "chain": null,
  "createdAt": "2025-01-15T10:00:00.000Z",
  "updatedAt": "2025-01-15T10:00:00.000Z"
}

If the badge is part of a chain, the chain field will contain the full chain object with its nested badges.

Delete badge by id

CURL example

curl --location -X DELETE 'https://chatbackend.watchers.io/external/badge/:id' --header 'Content-Type: application/json' --header 'Authorization: Bearer ${Bearer token from admin panel}' --header 'x-api-key: ${API KEY}'

Example response

true

Assign badge to user by userid (Replace)

Request payload

Parameter	Type	Required	Description
`userIds`	array of strings	Yes	Example { "userIds": ["123","321"] }

CURL example

curl --location -X POST 'https://chatbackend.watchers.io/external/badge/4/users' --header 'Content-Type: application/json' --header 'Authorization: Bearer ${Bearer token from admin panel}' --header 'x-api-key: ${API KEY}' --data ' { "userIds": ["123","321"] }'

Add badge to user by userid

Parameter	Type	Required	Description
`userIds`	array of strings	Yes	Example { "userIds": ["123","321"] }

CURL example

curl --location -X POST 'https://chatbackend.watchers.io/external/badge/4/users/add' --header 'Content-Type: application/json' --header 'Authorization: Bearer ${Bearer token from admin panel}' --header 'x-api-key: ${API KEY}' --data '{ "userIds": ["123", "321"] }'

{ "added": 2 }

Remove badge to user by userid

Parameter	Type	Required	Description
`userIds`	array of strings	Yes	Example { "userIds": ["123","321"] }

CURL example

curl --location -X POST 'https://chatbackend.watchers.io/external/badge/:badgeId/users/remove' { "userIds": string[] }'

{ "removed": number }

Required Headers for all API endpoints

Regional endpoints: Replace chatbackend.watchers.io with the endpoint matching your project region. See Supported Regions for details.

Create new badge

Update badge by id

Get list of all badges

Get badge by id

Delete badge by id

Assign badge to user by userid (Replace)

Add badge to user by userid

Remove badge to user by userid

Regional endpoints: Replace `chatbackend.watchers.io` with the endpoint matching your project region. See Supported Regions for details.