Теги

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

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

Теги в чате

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

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

За привязку отвечают методы POSTДобавление тегов и DELETEИсключение тега из чата. Оба относятся к составу участников и требуют скоуп chat_members:write. Текущие теги чата приходят в поле group_tag_ids объекта чата, и его же можно передать сразу при вызове POSTНовый чат.

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

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

В треде упоминание работает шире: пока в пространстве включены сквозные треды, сотрудники тега добавляются в сам тред, даже если в родительском чате их нет. Так тег собирает нужных сотрудников в обсуждение одной строкой. Кого добавляет упоминание от гостя и как выключить добавление параметром skip_invite_mentions метода POSTНовое сообщение, описано в разделе Участники треда.

Упоминания разбираются в момент отправки, поэтому тег, добавленный в текст позже методом PUTРедактирование сообщения, уведомление не рассылает.

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

Набор тегов сотрудника — это поле list_tags в методах POSTНовый сотрудник и PUTРедактирование сотрудника. В поле передаются названия тегов, а не идентификаторы, и присланный массив заменяет прежний набор целиком. Остальные поля сотрудника при этом можно не присылать.

• Названия создают теги. Если тега с таким названием в пространстве ещё нет, он создаётся вместе с назначением. Отдельно заводить его методом POSTНовый тег не нужно.
• Гостю теги не назначаются. Для роли guest поле пропускается без ошибки, а при переводе в гости все теги с сотрудника снимаются. Мульти-гостю теги назначаются, как сотруднику, и он попадает в чаты тега.
• Бота тоже можно отметить тегом. Условия, при которых бот может состоять в теге, описаны в разделе Бот в тегах.

Назначение и снятие тега пишутся в журнал аудита событиями user_added_to_tag и user_removed_from_tag.

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

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

• Снять с сотрудника тег через list_tags: тогда он выйдет из всех чатов этого тега
• Убрать тег из чата методом DELETEИсключение тега из чата: тогда выйдут все, кто попал в чат по этому тегу

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

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

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

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

Названия

Название задаётся при создании тега и меняется методом PUTРедактирование тега. Этот метод и POSTНовый тег проверяют, что название:

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

Эти методы сохраняют название как прислали, вместе с пробелами по краям. В поле list_tags у сотрудника пробелы по краям названий обрезаются, а одно и то же название, присланное дважды, считается за один тег. Тег из нового названия в list_tags на here и all не проверяется. Чтобы к тегу применились все правила, заводите его заранее методом POSTНовый тег.

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

По идентификатору тег отдаёт метод GETИнформация о теге. Когда известно только название, теги ищутся параметром names метода GETСписок тегов: он принимает до 100 названий за один запрос.

GET /api/shared/v1/group_tags?names[]=Дизайн&names[]=Питер

Права

Какие скоупы доступны каждой роли — в руководстве Права и роли.

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

Действия с тегами попадают в журнал аудита шестью событиями.

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

Событие tag_created пишут метод POSTНовый тег и создание тега в интерфейсе. Тег, который создался из нового названия в поле list_tags, события tag_created не оставляет: в журнале он появляется в событии user_added_to_tag.