Права API-ключа: какую роль выдать

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

Обновлено 2 ноября 2026 г.4 мин

Права API-ключа — это то, что программе разрешено делать в Chatterfy. Они зависят от двух ролей сервисного аккаунта: роли в компании и роли в каждом Space.

В статье — какую роль выбрать под задачу, какие права нужны методам API и почему API иногда отвечает «нет доступа» или «не найдено».

Как устроены права API-ключа

Ключ — это пропуск сервисного аккаунта. Что именно пропуск открывает, решают две роли:

Company role — права на уровне компании: видеть компанию и её участников, работать с Tracker;

Role in space — права на ботов и чаты конкретного Space. В каждом Space роль может быть своя.

Если сервисного аккаунта нет в Space, боты и чаты этого Space для API не существуют. Как добавить аккаунт в Space, написано в статье Как получить API-ключ.

Какую роль выбрать в Space для интеграции

Что делает интеграция	Роль в Space
Только читает чаты и сообщения	Space viewer
Читает, отвечает, меняет статусы и теги, выгружает чаты	Space controller
Всё, что выше, плюс аналитика, создание и удаление тегов, удаление чатов, настройки бота	Space manager
Всё, что выше, плюс управление самим Space и его участниками	Space administrator

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

Space operator и Space hidden operator не подходят для интеграций

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

Какую роль выбрать в компании для интеграции

Что делает интеграция	Роль в компании
Работает с ботами, чатами, сообщениями и аналитикой	Operator. Права на ботов придут из роли в Space
Работает с Tracker: кампании, домены, лендинги, лиды	Administrator. Buyer и Buyer team lead видят только кампании, где они указаны баером
Получает полный список участников компании	Owner или Administrator

Можно выдать и свою роль. Как собрать роль из нужных прав — в статье Кастомные роли — права компании и спейсов.

Права для работы с чатами и сообщениями

Права API-ключа на ботов, чаты и сообщения. Названия прав совпадают с ключами в поле access — по ним разбирают ошибку 403 и собирают свою роль:

Что делает интеграция	Право	В каких ролях есть
Видит ботов, их теги и поля	`bot.read`	Во всех ролях Space
Читает чаты	`chat.read`	Во всех ролях Space
Читает сообщения	`message.read`	Во всех ролях Space
Видит имена и username клиентов	`chat.contacts.read`	Во всех ролях Space, кроме Space hidden operator
Отправляет сообщения	`message.send`	Space controller и выше
Меняет статус, теги, ответственного и поля чата	`chat.manage`	Space controller и выше
Выгружает чаты	`chat.export`	Space controller и выше
Редактирует и удаляет сообщения	`message.manage`, `message.delete`	Space moderator, Space controller и выше

Права для аналитики, настроек бота, Space и Tracker

Права API-ключа на аналитику, теги и настройки бота, удаление чатов, участников Space и Tracker:

Что делает интеграция	Право	В каких ролях есть
Смотрит аналитику бота	`analytics.bot.read`	Space manager и выше
Создаёт и удаляет теги бота	`bot.settings.manage`	Space manager и выше
Меняет название, статус и описание бота	`bot.manage`	Space manager и выше
Удаляет чаты	`chat.delete`	Space manager и выше
Видит участников Space	`space.read`	Во всех ролях Space
Работает с кампаниями и лидами Tracker	`campaign.read`, `campaign.manage`	Administrator; Buyer и Buyer team lead — только свои
Работает с доменами и лендингами	`domain.read`, `domain.manage`, `landing.read`	Administrator; Buyer и Buyer team lead — только свои

Как узнать права ключа через поле access

Компании, Space и боты приходят в ответах API с полем access — это права сервисного аккаунта на этот объект. Например, так выглядит бот, к которому у аккаунта роль Space controller (часть полей скрыта):

{
  "id": "0b7c2e64-5d1f-4a8e-9c3b-2f6d8e1a4b90",
  "name": "Sales bot",
  "status": "active",
  "access": {
    "bot.read": "all",
    "chat.read": "all",
    "chat.manage": "all",
    "chat.export": "all",
    "message.read": "all",
    "message.send": "all"
  }
}

Права, которого нет в списке, у аккаунта нет. Значение рядом с правом — его широта:

Значение	Что значит
`all`	Все объекты: например, все чаты бота
`own_unassigned`	Свои и ни на кого не назначенные чаты
`own`, `assigned`	`own` — только чаты, назначенные на этот аккаунт. `assigned` — зависит от того, как в боте распределяются чаты: все чаты, свои и свободные или только свои

Ошибка 403 или 404 — в чём разница

Ответ	Что значит	Что делать
`403 access_denied`	Объект есть, но ключ к нему не допущен: у роли нет нужного права, объект в другой компании или в Space, куда аккаунт не добавлен, или чат не назначен на аккаунт	Проверьте, что аккаунт добавлен в нужный Space и у его роли есть право из таблицы выше
`404` с кодом `..._not_found`	Объекта с таким id нет: опечатка, объект удалён или передан id другого типа, например id чата вместо id бота	Проверьте id — берите его только из ответов API