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	Localized tooltips: a JSON string with an array of per-language objects, e.g. `"[{\"lang\":\"en\",\"tooltip\":\"...\"},{\"lang\":\"es\",\"tooltip\":\"...\"}]"`. The user sees the tooltip matching their interface language, with a fallback to the first entry. See Localized tooltips below.
`trigger`	object	No	Automatic badge assignment trigger configuration. See Badge Triggers for details.

CURL example

JavaScript

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

JSON

{
  "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	Localized tooltips: a JSON string with an array of per-language objects, e.g. `"[{\"lang\":\"en\",\"tooltip\":\"...\"},{\"lang\":\"es\",\"tooltip\":\"...\"}]"`. The user sees the tooltip matching their interface language, with a fallback to the first entry. See Localized tooltips below.
`trigger`	object	No	Automatic badge assignment trigger configuration. See Badge Triggers for details.

CURL example

JavaScript

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

JSON

true

Localized tooltips

Badges support tooltips in several languages via the data field, available in both create (POST) and update (PATCH) requests. Pass a JSON string containing an array of { "lang": "...", "tooltip": "..." } objects, one per language:

JavaScript

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": "VIP",
    "backgroundColor": "#ffc2fb",
    "textColor": "#000000",
    "tooltip": "For our most active users",
    "data": "[{\"lang\":\"en\",\"tooltip\":\"For our most active users\"},{\"lang\":\"es\",\"tooltip\":\"Para nuestros usuarios más activos\"}]"
}'

The user sees the tooltip matching their interface language. If there is no matching entry, the first entry in the array is used. The top-level tooltip field stays as the base value.

To update translations on an existing badge, send the same data field via PATCH:

JavaScript

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 '{
    "data": "[{\"lang\":\"en\",\"tooltip\":\"For our most active users\"},{\"lang\":\"es\",\"tooltip\":\"Para nuestros usuarios más activos\"},{\"lang\":\"fr\",\"tooltip\":\"Pour nos utilisateurs les plus actifs\"}]"
}'

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

JavaScript

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

JSON

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

JavaScript

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

JSON

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

JavaScript

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

JavaScript

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

JavaScript

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

Text

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

Text

{ "added": 2 }

Remove badge to user by userid

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

CURL example

Text

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

Text

{ "removed": number }

Updated 2 months ago