Поставить и снять теги

Ставит и снимает теги контактам, найденным по полю. За один вызов можно изменить теги в нескольких категориях.

POST /public/contacts/tags

Метод работает только с категориями и тегами, которые уже есть в Polygram. Их список отдаёт Категории тегов.

Чем отличается от Поставить тег:

можно снимать теги, а не только ставить;
за один запрос меняются теги из разных категорий;
новые теги не создаются: незнакомое название вернёт ошибку;
записи списка не меняются, final нет.

Тело запроса

Поле	Тип	Обязательное	Описание
`match.field`	строка	да	Ключ поля или колонка списка, 1–64 символа: латиница, цифры, `_ . -`. См. поиск по полю
`match.value`	строка или число	да	Значение поля. Пробелы по краям обрезаются. На пустое значение придёт ошибка
`add`	массив	нет	Теги, которые нужно поставить, до 50 штук
`remove`	массив	нет	Теги, которые нужно снять, до 50 штук
`add[].category`, `remove[].category`	строка	да	Название категории, 1–100 символов, без учёта регистра
`add[].tag`, `remove[].tag`	строка	да	Название тега в этой категории, 1–100 символов, без учёта регистра
`source`	строка	нет	Подпись источника для события в ленте, 1–60 символов. По умолчанию `Внешняя система`

Нужен хотя бы один тег в add или в remove.

{
  "match": { "field": "crm_id", "value": "1042" },
  "add": [
    { "category": "Статус аккаунта", "tag": "Активен" },
    { "category": "Интересы", "tag": "Опт" }
  ],
  "remove": [
    { "category": "Интересы", "tag": "Розница" }
  ],
  "source": "CRM"
}

Как меняются теги

Тег из add ставится, тег из remove снимается. Остальные теги контакта не меняются.
В категории, где можно выбрать только один тег, поставленный тег заменяет прежний: остальные теги этой категории снимаются сами.
Если тег уже стоит или уже снят, с ним ничего не происходит. Поэтому запрос можно безопасно повторять.
Метод меняет теги и в категориях с Ставит только внешняя система.

Ответ

200 OK.

{
  "matched": 1,
  "changed": 1
}

Поле	Описание
`matched`	Сколько контактов нашлось по полю
`changed`	У скольких контактов изменились теги

Если контакт не найден, придёт matched: 0 без ошибки.

Ошибки

Код	Когда
400	Поля не прошли проверку или нет ни `add`, ни `remove`
401	Нет ключа доступа или он неверный
422	Нет категории или тега с таким названием. В ответе перечислено всё, что не нашлось
422	Один и тот же тег есть и в `add`, и в `remove`
422	В `add` два тега из категории, где можно выбрать только один

При ошибке 422 теги не меняются ни у одного контакта.

Что происходит в Polygram

Для каждого контакта, у которого изменились теги:

в ленту всех диалогов контакта пишется событие о том, какие теги добавлены и сняты;
запускаются workflow с запуском Поставили тег на каждый поставленный тег и Сняли тег на каждый снятый. Workflow запускается в открытом диалоге контакта с последней активностью, а если открытых нет, то в последнем диалоге. Если у контакта нет диалогов, workflow не запускаются;
обновляются счётчики в списке чатов.

Пуш-уведомления сотрудникам не отправляются.

Пример

Снять тег:

curl -X POST https://api.polygram.chat/api/public/contacts/tags \
  -H "X-Api-Key: ak_..." \
  -H "Content-Type: application/json" \
  -d '{
    "match": { "field": "crm_id", "value": "1042" },
    "remove": [{ "category": "Интересы", "tag": "Розница" }],
    "source": "CRM"
  }'