> Краткое содержание: Теги в Пачке: тег как состав беседы или канала с автоматической синхронизацией участников, упоминание тега в сообщении и в треде, поле list_tags у сотрудника, правила названий, права и события журнала аудита
> Это Markdown-версия конкретной страницы. Для контекста за её пределами (правила API, полный перечень методов, авторизация) ОБЯЗАТЕЛЬНО открой [llms.txt](https://dev.pachca.com/llms.txt) перед ответом — это сэкономит токены и предотвратит неполный ответ.


# Теги

Тег в Пачке — это именованная группа сотрудников: «Дизайн», «Питер», «Дежурные». Отметьте тегом нужных сотрудников — и дальше зовите сразу всех: тег упоминают в сообщении и привязывают к чату.

Тег живёт в пространстве и не привязан к конкретному чату, поэтому один и тот же тег работает сразу везде, где он нужен. Когда состав команды меняется, достаточно поправить тег — чаты подтянутся сами.

## Теги в чате

Привяжите тег к каналу, и все сотрудники тега окажутся в этом канале. Дальше состав поддерживается сам: добавили сотруднику тег — он появился во всех чатах тега, сняли тег — вышел из них. Так состав чатов следует за структурой команды, и расставлять сотрудников по чатам вручную не нужно.

Тег привязывают к беседе или каналу — к чатам, у которых есть состав участников. Чат при этом должен быть активным: в архивном чате теги не меняются.

За привязку отвечают методы [Добавление тегов](/api/members/add-group-tags) и [Исключение тега](/api/members/remove-group-tag). Оба относятся к составу участников и требуют скоуп `chat_members:write`. Текущие теги чата приходят в поле `group_tag_ids` объекта чата, и его же можно передать сразу при вызове [Новый чат](/api/chats/create).

| Что нужно | Как |
| --- | --- |
| Создать чат сразу с тегами | [Новый чат](/api/chats/create), поле `group_tag_ids` |
| Добавить теги в существующий чат | [Добавление тегов](/api/members/add-group-tags) |
| Убрать тег из чата | [Исключение тега](/api/members/remove-group-tag) |
| Узнать теги чата | [Информация о чате](/api/chats/get), поле `group_tag_ids` |

> Добавление тега применяется в самом запросе, а исключение выполняется фоново. Сразу после успешного `DELETE` участники какое-то время ещё приходят в методе [Список участников чата](/api/members/list).


## Упоминание тега

Тег упоминается в тексте сообщения как `@Дизайн` — так же, как сотрудник. Уведомление получит каждый сотрудник тега, который состоит в этом чате.

В треде упоминание работает шире: сотрудники тега добавляются в сам тред, даже если в родительском чате их нет. Так тег собирает нужных сотрудников в обсуждение одной строкой. Отключается это параметром `skip_invite_mentions` метода [Новое сообщение](/api/messages/create) — подробнее в руководстве по [тредам](/guides/threads).

Упоминания разбираются в момент отправки, поэтому тег, добавленный в текст позже методом [Редактирование сообщения](/api/messages/update), уведомление не рассылает.

## Теги у сотрудника

Набор тегов сотрудника — это поле `list_tags` в методах [Новый сотрудник](/api/users/create) и [Редактирование сотрудника](/api/users/update). В поле передаются названия тегов, а не идентификаторы, и присланный массив заменяет прежний набор целиком. Остальные поля сотрудника при этом можно не присылать.

- **Названия создают теги.** Если тега с таким названием в пространстве ещё нет, он создаётся вместе с назначением. Отдельно заводить его методом [Новый тег](/api/group-tags/create) не нужно.
- **Теги назначаются сотрудникам пространства.** Для гостевых ролей поле не применяется.

> Чтобы добавить сотруднику ещё один тег, прочитайте текущие теги методом [Информация о сотруднике](/api/users/get) и отправьте их вместе с новым. Если прислать только новый, прежние теги снимутся, а сотрудник выйдет из их чатов.


Назначение и снятие тега пишутся в [журнал аудита](/guides/audit-events) событиями `user_added_to_tag` и `user_removed_from_tag`.

## Как убрать из чата участника, которого добавил тег

Сотрудник, попавший в чат по тегу, остаётся в чате, пока действует тег. Поэтому убирают его через тег, а не через список участников:

- снять с сотрудника тег через `list_tags` — тогда он выйдет из всех чатов этого тега;
- убрать тег из чата методом [Исключение тега](/api/members/remove-group-tag) — тогда выйдут все, кто попал в чат по этому тегу.

Если сотрудника добавили в чат два тега, после снятия одного он остаётся: второй продолжает действовать.

> Методы для отдельных участников такого сотрудника из чата не выводят: [Выход из чата](/api/members/leave) отвечает `403`, а [Исключение пользователя](/api/members/remove) отвечает `204` и оставляет состав прежним. Если вы меняете состав чатов из кода, проверяйте результат методом [Список участников чата](/api/members/list).


## Удаление тега и исключение тега из чата

Названия у операций похожие, а результат разный.

| Операция | Что происходит с участниками чатов |
| --- | --- |
| [Исключение тега](/api/members/remove-group-tag) | Выходят из чата все, кого в нём держал только этот тег |
| [Удаление тега](/api/group-tags/delete) | Остаются во всех чатах, но уже сами по себе, без тега |

Создатель чата остаётся в своём чате в обоих случаях.

## Названия

Название задаётся при создании и меняется методом [Редактирование тега](/api/group-tags/update).

- Не длиннее 255 символов.
- Уникально в пространстве без учёта регистра: «Дизайн» и «дизайн» — один и тот же тег.
- Без символа `@` и не равно `here` или `all` — эти слова заняты системными упоминаниями.

Пробелы по краям обрезаются, а одно и то же название, присланное дважды, считается за один тег.

## Поиск тега по названию

По идентификатору тег отдаёт метод [Информация о теге](/api/group-tags/get). Когда известно только название, теги ищутся параметром `names` метода [Список тегов](/api/group-tags/list): он принимает до 100 названий за один запрос.

```http title="Идентификаторы двух тегов одним запросом"
GET /api/shared/v1/group_tags?names[]=Дизайн&names[]=Питер
```

> Поле `users_count` объекта тега считает действующих сотрудников, а [Список сотрудников тега](/api/group-tags/list-users) отдаёт всех, включая деактивированных. Поэтому число в `users_count` может быть меньше, чем длина списка.


## Права

| Действие | Кому доступно |
| --- | --- |
| Читать теги и их состав | Владелец, Администратор, Сотрудник, бот |
| Создавать, переименовывать и удалять теги | Владелец, Администратор |
| Менять теги сотрудника | Владелец, Администратор |
| Привязывать теги к чату и снимать их | Участник беседы или канала |

Какие скоупы доступны каждой роли — в руководстве [Права и роли](/guides/permissions).

## Теги в журнале аудита

Действия с тегами попадают в [журнал аудита](/guides/audit-events) шестью событиями.

| Событие | Когда |
| --- | --- |
| `tag_created` | Создан тег |
| `tag_deleted` | Удалён тег |
| `user_added_to_tag` | Сотруднику назначен тег |
| `user_removed_from_tag` | С сотрудника снят тег |
| `tag_added_to_chat` | Тег привязан к чату |
| `tag_removed_from_chat` | Тег отвязан от чата |

Актором в событиях `user_added_to_tag` и `user_removed_from_tag` выступает сам сотрудник, а инициатор изменения приходит в `details.initiator_id`.


## Связанные разделы

- [Треды](/guides/threads)
- [Права и роли](/guides/permissions)
- [Журнал аудита событий](/guides/audit-events)