# Etiquetas

Estos métodos muestran las [etiquetas](https://support.jetbot24.ru/es/chatbots/contacts/tags-variables#etiquetas) de un bot y de un contacto, y las asignan y quitan. Por ejemplo, tras un pago en tu sitio web puedes dar al contacto la etiqueta «paid» y luego comprobarla en un flujo con el bloque [Condición](https://support.jetbot24.ru/es/chatbots/blocks/logic/condition) o usarla para elegir los destinatarios de un envío masivo.

Una etiqueta es solo una cadena: no hace falta crearla de antemano. Las mayúsculas importan: «VIP» y «vip» son etiquetas distintas.

## getBotTags

Devuelve la lista «Sugerencias de etiquetas» del bot: los nombres de etiquetas que se escribieron en la cuenta.

```endpoint
GET POST https://app.jetbot24.ru/api/v1/getBotTags
```

| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `bot_id` | entero | sí | ID del bot |

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

Detalles:

- La lista de sugerencias no es una lista completa de las etiquetas de los contactos. Contiene los nombres introducidos en la cuenta y las etiquetas nuevas asignadas con `attachTagToContact` (mientras la lista tenga menos de 5000 nombres). Las etiquetas que asignan los bloques del flujo no se añaden a ella por sí solas, y quitar un nombre de la lista no quita la etiqueta a los contactos.
- Bot no encontrado o eliminado: `404`; bot ajeno: `403`.

## getContactTags

Devuelve las etiquetas de un contacto.

```endpoint
GET POST https://app.jetbot24.ru/api/v1/getContactTags
```

| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `contact_id` | entero | sí | ID del contacto |

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

Si el contacto no tiene etiquetas, `data` es un array vacío. Contacto no encontrado o eliminado, o su bot eliminado: `404`; contacto de un bot ajeno: `403`.

## attachTagToContact

Asigna una etiqueta a un contacto.

```endpoint
GET POST https://app.jetbot24.ru/api/v1/attachTagToContact
```

| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `contact_id` | entero | sí | ID del contacto |
| `name` | cadena | sí | Nombre de la etiqueta, hasta 60 caracteres (como en la cuenta): letras, dígitos, espacios, `_`, `.` y `-` |

```bash title="Solicitud"
curl -X POST "https://app.jetbot24.ru/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="Respuesta 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."]
  }
}
```

La respuesta tiene el estado `204` y no tiene cuerpo.

Detalles:

- Si el contacto ya tiene la etiqueta, no se añade otra vez; la respuesta es el mismo `204`.
- Un contacto puede tener como máximo 1000 etiquetas. Por encima de eso, el método no asigna la etiqueta nueva y responde con `422` y `code: "tags_limit"`.
- Una etiqueta nueva también se añade a la lista de sugerencias del bot: `getBotTags` la devuelve.
- Contacto no encontrado o eliminado, o su bot eliminado: `404`; contacto de un bot ajeno: `403`.

## detachTagFromContact

Quita una etiqueta a un contacto.

```endpoint
GET POST https://app.jetbot24.ru/api/v1/detachTagFromContact
```

| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `contact_id` | entero | sí | ID del contacto |
| `name` | cadena | sí | Nombre de la etiqueta, hasta 255 caracteres, para poder quitar también una etiqueta larga asignada por un bloque del flujo |

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

La respuesta tiene el estado `204` y no tiene cuerpo. Si el contacto no tenía la etiqueta, la respuesta es la misma.

Contacto no encontrado o eliminado, o su bot eliminado: `404`; contacto de un bot ajeno: `403`.

Los errores generales de la API se describen en [Errores](https://support.jetbot24.ru/es/api#errores).