Documentation

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.

RegionEndpoint
Europe (default)chatbackend.watchers.io
North Americachatbackend.us.watchers.io
South Americachatbackend.sa.watchers.io
Asiachatbackend.hk.watchers.io
Africachatbackend.za.watchers.io
ParameterDescription
x-api-keyYour public API key used for the project
AuthorizationBearer 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

ParameterTypeRequiredDescription
textstringYesText on badge. Better use not more than 10-12 characters, and also use emoji. (Not limited)
backgroundColorstringYesHEX Color of badge
textColorstringYesHEX Color of text
tooltipstringYesShort description for badge.
Limited to 140 characters.
communicationPicstringYesThe 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
communicationTitlestringYesThe message title that the user will see when entering the chat when he has been assigned this badge.
Limited to 140 characters.
communicationTextstringYesThe message text that the user will see when entering the chat when he has been assigned this badge.
Limited to 180 characters.
picstringNoURL of the badge image/icon.
datastringNoLocalized 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.
triggerobjectNoAutomatic 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

ParameterTypeRequiredDescription
textstringYesText on badge. Better use not more than 10-12 characters, and also use emoji. (Not limited)
backgroundColorstringYesHEX Color of badge
textColorstringYesHEX Color of text
tooltipstringYesShort description for badge.
Limited to 140 characters.
communicationPicstringYesThe 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
communicationTitlestringYesThe message title that the user will see when entering the chat when he has been assigned this badge.
Limited to 140 characters.
communicationTextstringYesThe message text that the user will see when entering the chat when he has been assigned this badge.
Limited to 180 characters.
picstringNoURL of the badge image/icon.
datastringNoLocalized 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.
triggerobjectNoAutomatic 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

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:

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:

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

ParameterTypeRequiredDescription
limitnumberNoNumber of badges to return (default: 20)
offsetnumberNoNumber of badges to skip for pagination (default: 0)
orderstringNoSort 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

ParameterTypeRequiredDescription
userIdsarray of stringsYesExample { "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

ParameterTypeRequiredDescription
userIdsarray of stringsYesExample { "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

ParameterTypeRequiredDescription
userIdsarray of stringsYesExample { "userIds": ["123","321"] }

CURL example

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"] }'
{ "removed": number }

Updated about 1 month ago

Did this page help you?