# Tags

These methods show the [tags](https://support.watbot.org/chatbots/contacts/tags-variables#tags) of a bot and a contact, and assign and remove them. For example, after a payment on your website you can give the contact the tag "paid", then check it in a scenario with the [Condition](https://support.watbot.org/chatbots/blocks/logic/condition) block or use it to pick mailing recipients.

A tag is just a string: you do not need to create it in advance. Case matters: "VIP" and "vip" are different tags.

## getBotTags

Returns the bot's "Tag hints" list — tag names that were typed in the account.

```endpoint
GET POST https://watbot.org/api/v1/getBotTags
```

| Parameter | Type | Required | Description |
|---|---|---|---|
| `bot_id` | integer | yes | Bot ID |

```bash title="Request"
curl -X POST "https://watbot.org/api/v1/getBotTags" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"bot_id": 12345}'
```
```json title="Response 200"
{
  "data": ["vip", "paid", "newcomer"]
}
```

Details:

- The hint list is not a complete list of contacts' tags. It contains names entered in the account and new tags set with `attachTagToContact` (while the list holds fewer than 5000 names). Tags set by scenario blocks are not added to it on their own, and removing a name from the list does not remove the tag from contacts.
- Bot not found or deleted — `404`; someone else's bot — `403`.

## getContactTags

Returns a contact's tags.

```endpoint
GET POST https://watbot.org/api/v1/getContactTags
```

| Parameter | Type | Required | Description |
|---|---|---|---|
| `contact_id` | integer | yes | Contact ID |

```bash title="Request"
curl -X POST "https://watbot.org/api/v1/getContactTags" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"contact_id": 678}'
```
```json title="Response 200"
{
  "data": ["vip", "paid"]
}
```

If the contact has no tags, `data` is an empty array. Contact not found, deleted, or its bot deleted — `404`; contact from someone else's bot — `403`.

## attachTagToContact

Assigns a tag to a contact.

```endpoint
GET POST https://watbot.org/api/v1/attachTagToContact
```

| Parameter | Type | Required | Description |
|---|---|---|---|
| `contact_id` | integer | yes | Contact ID |
| `name` | string | yes | Tag name, up to 60 characters (as in the account): letters, digits, spaces, `_`, `.` and `-` |

```bash title="Request"
curl -X POST "https://watbot.org/api/v1/attachTagToContact" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"contact_id": 678, "name": "paid"}'
```
```json title="Response 422"
{
  "message": "The contact already has 1000 tags — no more can be added.",
  "error": "The contact already has 1000 tags — no more can be added.",
  "code": "tags_limit",
  "errors": {
    "name": ["The contact already has 1000 tags — no more can be added."]
  }
}
```

The response is status `204` with no body.

Details:

- If the contact already has the tag, it is not added a second time — the response is the same `204`.
- A contact can have at most 1000 tags. Beyond that the method does not set a new tag and responds with `422` and `code: "tags_limit"`.
- A new tag is also added to the bot's hint list — `getBotTags` returns it.
- Contact not found, deleted, or its bot deleted — `404`; contact from someone else's bot — `403`.

## detachTagFromContact

Removes a tag from a contact.

```endpoint
GET POST https://watbot.org/api/v1/detachTagFromContact
```

| Parameter | Type | Required | Description |
|---|---|---|---|
| `contact_id` | integer | yes | Contact ID |
| `name` | string | yes | Tag name, up to 255 characters — so a long tag set by a scenario block can be removed too |

```bash title="Request"
curl -X POST "https://watbot.org/api/v1/detachTagFromContact" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"contact_id": 678, "name": "paid"}'
```

The response is status `204` with no body. If the contact did not have the tag, the response is the same.

Contact not found, deleted, or its bot deleted — `404`; contact from someone else's bot — `403`.

General API errors are described under [Errors](https://support.watbot.org/api#errors).