---
title: Badges API
updatedAt: 2026-07-06T12:54:58.000Z
---

Fetch the complete documentation index at: https://docs.watchers.io/llms.txt

# 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](https://docs.watchers.io/docs/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` |

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

<table class="docs-table">
  <thead><tr> <th> Parameter</th>
      <th><b>Type</b></th>
      <th><b>Required</b></th>
      <th><b>Description</b></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>`text`</td>
      <td>string</td>
      <td>Yes</td>
      <td>Text on badge. Better use not more than 10-12 characters, and also use emoji. (Not limited)</td>
    </tr>
    <tr>
      <td>`backgroundColor`</td>
      <td>string</td>
      <td>Yes</td>
      <td>HEX Color of badge</td>
    </tr>
    <tr>
      <td>`textColor`</td>
      <td>string</td>
      <td>Yes</td>
      <td>HEX Color of text</td>
    </tr>
    <tr>
      <td>`tooltip`</td>
      <td>string</td>
      <td>Yes</td>
      <td>Short description for badge. Limited to 140 characters.</td>
    </tr>
    <tr>
      <td>`communicationPic`</td>
      <td>string</td>
      <td>Yes</td>
      <td>The message image that the user will see when entering the chat when he has been assigned this badge. <i> File size: No more than 10 MB </i> Dimensions: At least 190×190 px</td>
    </tr>
    <tr>
      <td>`communicationTitle`</td>
      <td>string</td>
      <td>Yes</td>
      <td>The message title that the user will see when entering the chat when he has been assigned this badge. Limited to 140 characters.</td>
    </tr>
    <tr>
      <td>`communicationText`</td>
      <td>string</td>
      <td>Yes</td>
      <td>The message text that the user will see when entering the chat when he has been assigned this badge. Limited to 180 characters.</td>
    </tr>
      <tr>
      <td>`pic`</td>
      <td>string</td>
      <td>No</td>
      <td>URL of the badge image/icon.</td>
    </tr>
    <tr>
      <td>`data`</td>
      <td>string</td>
      <td>No</td>
      <td>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 <b>Localized tooltips</b> below.</td>
    </tr>
    <tr>
      <td>`trigger`</td>
      <td>object</td>
      <td>No</td>
      <td>Automatic badge assignment trigger configuration. See <a href="https://docs.watchers.io/docs/badge-triggers-automatic-badge-assignment">Badge Triggers</a> for details.</td>
    </tr>
</tbody>
</table>

<br>

**CURL example**

```javascript Bash
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**

<table class="docs-table">
  <thead><tr> <th> Parameter</th>
      <th><b>Type</b></th>
      <th><b>Required</b></th>
      <th><b>Description</b></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>`text`</td>
      <td>string</td>
      <td>Yes</td>
      <td>Text on badge. Better use not more than 10-12 characters, and also use emoji. (Not limited)</td>
    </tr>
    <tr>
      <td>`backgroundColor`</td>
      <td>string</td>
      <td>Yes</td>
      <td>HEX Color of badge</td>
    </tr>
    <tr>
      <td>`textColor`</td>
      <td>string</td>
      <td>Yes</td>
      <td>HEX Color of text</td>
    </tr>
    <tr>
      <td>`tooltip`</td>
      <td>string</td>
      <td>Yes</td>
      <td>Short description for badge. Limited to 140 characters.</td>
    </tr>
    <tr>
      <td>`communicationPic`</td>
      <td>string</td>
      <td>Yes</td>
      <td>The message image that the user will see when entering the chat when he has been assigned this badge. <i> File size: No more than 10 MB </i> Dimensions: At least 190×190 px</td>
    </tr>
    <tr>
      <td>`communicationTitle`</td>
      <td>string</td>
      <td>Yes</td>
      <td>The message title that the user will see when entering the chat when he has been assigned this badge. Limited to 140 characters.</td>
    </tr>
    <tr>
      <td>`communicationText`</td>
      <td>string</td>
      <td>Yes</td>
      <td>The message text that the user will see when entering the chat when he has been assigned this badge. Limited to 180 characters.</td>
    </tr>
      <tr>
      <td>`pic`</td>
      <td>string</td>
      <td>No</td>
      <td>URL of the badge image/icon.</td>
    </tr>
    <tr>
      <td>`data`</td>
      <td>string</td>
      <td>No</td>
      <td>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 <b>Localized tooltips</b> below.</td>
    </tr>
    <tr>
      <td>`trigger`</td>
      <td>object</td>
      <td>No</td>
      <td>Automatic badge assignment trigger configuration. See <a href="https://docs.watchers.io/docs/badge-triggers-automatic-badge-assignment">Badge Triggers</a> for details.</td>
    </tr>
</tbody>
</table>

<br>

**CURL example**

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

<br>

## Add badge to user by userid

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

**CURL example**

```Text Bash
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 Response
{ "added": 2 }
```

<br>

## Remove badge to user by userid

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

**CURL example**

```Text Bash
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 Response
{ "removed": number }
```