Как изменить чат через API: статус, теги, ответственный, поля

Изменение чата через API — это то же, что правка карточки клиента в приложении: смена статуса, ответственного, тегов и полей. Всё делается одним запросом PATCH , в котором вы передаёте только то, что

Обновлено 2 ноября 2026 г.3 мин
Изменение чата через API — это то же, что правка карточки клиента в приложении: смена статуса, ответственного, тегов и полей. Всё делается одним запросом PATCH, в котором вы передаёте только то, что меняете.
В статье — как сменить статус, назначить ответственного, поставить или снять тег, заполнить поле, создать новый тег и удалить чат.


Что понадобится

  1. API-ключ с ролью Space controller или выше. Создавать теги и удалять чаты может Space manager и выше — Права API-ключа: какую роль выдать.
  1. id чата — Как получить чаты и сообщения через API.


Как устроен запрос на изменение чата

Чат меняет запрос PATCH /chats/v1/{chat_id}. Нужна роль Space controller или выше.
PATCH
https://api.chatterfy.ai/public-api/chats/v1/{chat_id}

Изменить чат


В теле передайте только поля, которые меняете. Остальное останется как было. В ответ придёт чат уже с изменениями.
Поле
Что меняет
status
Статус чата
assign_id
Ответственного
tags
Теги: какие поставить и какие снять
custom_fields
Значения полей
Пустое тело {} API не примет и вернёт ошибку no_fields.


Смените статус чата

Статус чата меняет поле status в PATCH /chats/v1/{chat_id}. Например, так чат переходит к оператору:
Перевести чат операторуbash
curl -X PATCH 'https://api.chatterfy.ai/public-api/chats/v1/ID_ЧАТА' \
  -H 'ApiKey: ВАШ_КЛЮЧ' \
  -H 'Content-Type: application/json' \
  -d '{"status": "manual"}'
Значение
Статус в приложении
Что значит
ai
Auto
AI ведёт диалог автоматически
manual
Manual
Диалог в ручной обработке у оператора
blocked
Blocked
Чат заблокирован со стороны CRM
stopped
Stopped
Бот больше не пишет в этот диалог
Ещё можно передать start и ignore. Подробно о каждом статусе — в статье Chat Status — статусы диалога.


Назначьте ответственного за чат

Ответственного за чат задаёт поле assign_id в PATCH /chats/v1/{chat_id} — это id участника Space, в котором находится бот.

  1. Найдите id сотрудника

    Запросите участников Space, в котором находится бот:
    Запросbash
    curl -X POST 'https://api.chatterfy.ai/public-api/spaces/v1/ID_SPACE/members/search' \
  -H 'ApiKey: ВАШ_КЛЮЧ'
    Возьмите id нужного человека из списка accounts.

  2. Назначьте его на чат

    Тело запроса PATCHjson
    {
  "assign_id": "ID_СОТРУДНИКА",
  "status": "manual"
}
Назначить можно только участника Space этого бота. Иначе API вернёт ошибку unknown_assignee.


Поставьте или снимите тег в чате

Теги чата передаются по id, а не по названию, в tags.assign и tags.remove запроса PATCH /chats/v1/{chat_id}. Сначала получите список тегов бота:
Теги ботаbash
curl 'https://api.chatterfy.ai/public-api/bots/v1/ID_БОТА/tags' \
  -H 'ApiKey: ВАШ_КЛЮЧ'
Затем в tags.assign перечислите теги, которые нужно поставить, а в tags.remove — которые снять. Остальные теги чата не изменятся.
Тело запроса PATCHjson
{
  "tags": {
    "assign": ["ID_ТЕГА_ОПЛАТИЛ"],
    "remove": ["ID_ТЕГА_ДУМАЕТ"]
  }
}
Тег другого бота API не примет и вернёт ошибку unknown_tag.


Создайте или удалите тег бота

Если нужного тега ещё нет, создайте его запросом POST /bots/v1/{bot_id}/tags. Нужна роль Space manager или выше.
Создать тегbash
curl -X POST 'https://api.chatterfy.ai/public-api/bots/v1/ID_БОТА/tags' \
  -H 'ApiKey: ВАШ_КЛЮЧ' \
  -H 'Content-Type: application/json' \
  -d '{"name": "Оплатил", "color": "#2E7D32"}'
name — до 64 символов, color — необязательный цвет в формате #RRGGBB. В ответе придёт id нового тега.
Удалить тег: DELETE /bots/v1/{bot_id}/tags/{tag_id}. Тег пропадёт у бота и у всех чатов, где стоял.


Заполните кастомные поля чата

Кастомные поля чата передаются в custom_fields по id поля. Получите список полей бота:
Поля ботаbash
curl 'https://api.chatterfy.ai/public-api/bots/v1/ID_БОТА/custom-fields' \
  -H 'ApiKey: ВАШ_КЛЮЧ'
У каждого поля есть id, key и name. В custom_fields ключом записывайте именно id поля, а не key:
Тело запроса PATCHjson
{
  "custom_fields": {
    "ID_ПОЛЯ_ГОРОД": "Москва",
    "ID_ПОЛЯ_БЮДЖЕТ": "50000"
  }
}
Ключ — id поля, а не key
Если записать ключом key поля (например, city), API вернёт ошибку unknown_custom_field. Значения передаются строкой, даже числа.
Что такое поля и как их создать в приложении — в статье Custom Fields — пользовательские поля.


Измените статус, теги и поля одним запросом

Статус, ответственного, теги и поля можно передать в одном PATCH /chats/v1/{chat_id}:
Тело запроса PATCHjson
{
  "status": "manual",
  "assign_id": "ID_СОТРУДНИКА",
  "tags": { "assign": ["ID_ТЕГА"] },
  "custom_fields": { "ID_ПОЛЯ": "Москва" }
}
API сначала проверяет все id, и если хоть один не подходит, не меняет ничего.


Удалите чат через API

Чат удаляет запрос DELETE /chats/v1/{chat_id}:
Удалить чатbash
curl -X DELETE 'https://api.chatterfy.ai/public-api/chats/v1/ID_ЧАТА' \
  -H 'ApiKey: ВАШ_КЛЮЧ'
Удаление нельзя отменить
Чат удаляется вместе со всей перепиской. Нужна роль Space manager или выше.


Частые вопросы



Связанное

Как получить чаты и сообщения через API
Чаты и сообщения через API читаются двумя запросами: сначала список чатов бота, потом сообщения нужного чата. Это то же самое, что открыть бота в приложении и нажать на диалог. В статье — как получить
Фильтры чатов в API
Фильтр чатов — это условия, по которым API отбирает чаты: например, «непрочитанные», «с тегом Оплатил» или «пришли из Google». Один и тот же фильтр работает в поиске, подсчёте, выгрузке и подписке на
Tags — теги для сегментации
Раздел Bot Settings → Tags — теги для маркировки лидов.
Custom Fields — пользовательские поля
(Bot Settings → Custom Fields) — раздел для создания дополнительных полей в карточке клиента.

Эта статья была полезна?