Для разработчиков

Ротация токена бота

POST/bots/{id}/recreate_token

Метод генерирует боту новый access_token и сразу инвалидирует прежний. Используйте его при компрометации токена или плановой ротации секрета в CI.

Перевыпускается основной токен бота — тот, что без имени, а если такого нет, самый старый. Прежний токен удаляется, а новый создаётся с новым идентификатором и без имени. Метод POSTПеревыпуск токена бота сохраняет имя и идентификатор токена и меняет одно значение: так перевыпускают отдельный токен и основной токен с именем.

Новый токен возвращается в ответе только один раз — сохраните его сразу. Права у него те же: скоупы переносятся с прежнего токена. В webhook ответа приходят адрес входящего вебхука url, секрет подписи secret_token и тело последнего запроса на входящий вебхук last_request_body.

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

Параметры пути

id
integer, (int32)
*
Идентификатор бота
Пример:1738816

Ответ

200OK
The request has succeeded.
data
object
*
Параметры созданного бота
id
integer, (int32)
*
Идентификатор бота (совпадает с user_id бота)
Пример:1738816
name
string
*
Имя бота
Пример:Бот задач
nickname
string
*
Никнейм бота
Пример:tasks_bot
avatar_url
nullablestring
*
Ссылка на аватар бота. null, если аватар не задан.
Пример:https://files.example.com/uploads/0001/0001/image.jpg
creator_id
nullableinteger, (int32)
*
Идентификатор сотрудника, создавшего бота. null, если создатель не записан.
Пример:12
created_at
string, (date-time)
*
Дата и время создания бота (ISO-8601, UTC+0) в формате YYYY-MM-DDThh:mm:ss.sssZ
Пример:2025-05-15T14:30:00.000Z
authorized_users_count
integer, (int32)
*
Сколько сотрудников авторизовали бота
Пример:3
last_used_at
nullablestring, (date-time)
*
Дата и время, когда бот последний раз работал (ISO-8601, UTC+0) в формате YYYY-MM-DDThh:mm:ss.sssZ: запрос на входящий вебхук или вызов API любым токеном бота, включая токены сотрудников. null, если такого не было. Использование токена учитывается не чаще раза в минуту.
Пример:2025-05-15T14:30:00.000Z
webhook
object
*
Объект параметров вебхука
name
string
*
Имя бота
Пример:Бот задач
Длина:
<= 255 символов
nickname
string
*
Никнейм бота
Пример:tasks_bot
Длина:
<= 255 символов
outgoing_url
nullablestring
*
URL исходящего вебхука. null или пустая строка, если адрес не задан: бот тогда получает события только из истории событий, если она включена.
Пример:https://example.com/tasks/new
events[]
array of strings
*
События, на которые подписан бот
Возможные значения
Пример:["message_new"]
trigger_on
string
*
Условие срабатывания исходящего вебхука
Возможные значения
Пример:commands
commands[]
array of strings
*
Команды бота (триггер-слова)
Пример:["/task"]
scopes[]
array of strings
*
Скоупы (права доступа) токена бота. Набор по умолчанию шире того, что можно назначить явно, поэтому здесь могут встречаться значения, недоступные для явной установки.
Пример:["messages:create"]
template
nullablestring
*
Шаблон форматирования входящего вебхука. null, если не задан.
Пример:Заказ от {{ client }} на сумму {{ amount }} ₽
template_engine
string
*
Шаблонизатор для обработки шаблона входящего вебхука
Возможные значения
Пример:liquid
challenge_key
nullablestring
*
Название поля проверки для верификации входящего вебхука. null, если не задано.
Пример:challenge
ignore_self_messages
boolean
*
Не присылать боту события о сообщениях, которые он отправил сам, и о реакциях на эти сообщения, кто бы их ни поставил или снял. Нажатия кнопок приходят всегда.
Пример:false
events_history_enabled
boolean
*
Сохранять историю событий бота для последующего получения через метод истории событий
Пример:false
single_chat
boolean
*
Ограничивает бота одной беседой или каналом: true — бота можно добавить только в один такой чат, false — в несколько. Личные чаты и треды в ограничение не входят.
Пример:false
can_edit[]
array of strings
*
Роли, которым, помимо создателя, разрешено редактировать настройки бота. Создатель может редактировать всегда. Пустой массив — редактировать может только создатель.
Возможные значения
Пример:["admin"]
who_can_add
string
*
Кто может добавлять бота в чаты
Возможные значения
Пример:creator
kind
nullablestring
*
Источник входящего вебхука. null, если входящий вебхук у бота выключен.
Возможные значения
Пример:simple
unfurl_domains[]
array of strings
*
Домены, ссылки на которые бот разворачивает
Пример:["example.com"]
last_request_at
nullablestring, (date-time)
*
Дата и время последнего запроса на входящий вебхук бота (ISO-8601, UTC+0) в формате YYYY-MM-DDThh:mm:ss.sssZ. null, если запросов не было.
Пример:2025-05-15T14:30:00.000Z
url
nullablestring
Адрес входящего вебхука. null, если входящий вебхук у бота выключен. Приходит в ответе об одном боте токену со скоупом bots:write, который может управлять токенами бота (permissions.recreate_token).
Пример:https://api.pachca.com/webhooks/01JAXK7R3B5Y8Q2W4E6T9V1N3M
secret_token
string
Секрет подписи исходящего вебхука: им подписан заголовок Pachca-Signature. Приходит в ответе об одном боте токену со скоупом bots:write, который может управлять токенами бота (permissions.recreate_token).
Пример:pachca_wh_3pX9vQ2mL7rT5yW8kN4bH6jF1dS0aZcVxE2uI9oP7qR3tY5wK8nM4gB6hJ1lD0fA
last_request_body
nullablestring
Тело последнего запроса на входящий вебхук бота. Длиннее 128 КБ обрезается и заканчивается на ...[truncated]. null, если запросов не было. Приходит в ответе об одном боте токену со скоупом bots:write, который может управлять токенами бота (permissions.recreate_token).
Пример:{"client": "ООО Ромашка", "amount": 15000}
oauth_client_enabled
boolean
*
Включена ли у бота авторизация от имени сотрудника
Пример:true
oauth_client
nullableobject
*
Параметры авторизации от имени сотрудника. Может прийти и у бота с выключенной авторизацией, поэтому включена ли она, смотрите в oauth_client_enabled. У бота без токенов может прийти null.
client_id
string
*
Идентификатор клиента для ссылки авторизации
Пример:aB3dE5fG7hJ9kL1mN3pQ5rS7tU9vW1xY
client_secret_preview
string
*
Секрет клиента в маскированном виде. Полное значение приходит в client_secret один раз: при включении серверного клиента, при переключении клиента на серверный и при ротации секрета.
Пример:cH5kR9mN...x7Qp
confidential
boolean
*
Где хранится секрет: true — серверное приложение, false — приложение без секрета, обмен кода по PKCE
Пример:true
redirect_uris[]
array of strings
*
Адреса возврата после согласия
Пример:["https://example.com/oauth/callback"]
scopes[]
array of strings
*
Права, которые бот запрашивает у сотрудника на экране согласия
Пример:["messages:read","messages:create"]
promo
nullableobject
*
Страница бота в витрине. null, если авторизация у бота выключена.
description
nullablestring
*
Описание бота. null, если не задано.
Пример:Собирает сводку по задачам Jira и присылает её в чат
published
boolean
*
Опубликован ли бот в витрине
Пример:true
promo_images[]
array of objects
*
Скриншоты страницы бота
key
string
*
Ключ изображения
Пример:attaches/files/93746/e354fd79-4f3e-4b5a-9c8d-1a2b3c4d5e6f/screenshot.png
url
string
*
Ссылка на изображение
Пример:https://files.example.com/attaches/files/93746/e354fd79-4f3e-4b5a-9c8d-1a2b3c4d5e6f/screenshot.png
permissions
object
*
Что вы можете делать с этим ботом
update_oauth_client
boolean
*
Менять авторизацию от имени сотрудника, страницу в витрине и имя бота
Пример:true
recreate_token
boolean
*
Выпускать, менять и удалять токены бота и обновлять секрет клиента
Пример:true
destroy
boolean
*
Удалить бота
Пример:true
client_secret
string
Секрет клиента. Приходит один раз: при включении серверного клиента, при переходе на него и при ротации секрета.
Пример:dGhpc19pc19ub3RfYV9yZWFsX3NlY3JldA
access_token
string
Токен доступа бота. Возвращается при создании бота и при ротации токена. Не приходит, если бот создан с empty: true.
Пример:bm90X2FfcmVhbF90b2tlbg
Ротация токена бота
pachca bots recreate-token 1738816 \  --json \  --token YOUR_ACCESS_TOKEN
Ответ 200
{  "data": {    "id": 1738816,    "name": "Бот задач",    "nickname": "tasks_bot",    "avatar_url": null,    "creator_id": 12,    "created_at": "2025-05-15T14:30:00.000Z",    "authorized_users_count": 3,    "last_used_at": "2025-05-20T09:15:00.000Z",    "webhook": {      "name": "Бот задач",      "nickname": "tasks_bot",      "outgoing_url": "https://example.com/tasks/new",      "events": [        "message_new"      ],      "trigger_on": "commands",      "commands": [        "/task"      ],      "scopes": [        "messages:create"      ],      "template": "Заказ от {{ client }} на сумму {{ amount }} ₽",      "template_engine": "liquid",      "challenge_key": "challenge",      "link_preview_enabled": true,      "ignore_self_messages": false,      "events_history_enabled": false,      "single_chat": false,      "can_edit": [        "admin"      ],      "who_can_add": "creator",      "kind": "simple",      "unfurl_domains": [],      "last_request_at": "2025-05-20T09:15:00.000Z",      "url": "https://api.pachca.com/webhooks/01JAXK7R3B5Y8Q2W4E6T9V1N3M",      "secret_token": "pachca_wh_3pX9vQ2mL7rT5yW8kN4bH6jF1dS0aZcVxE2uI9oP7qR3tY5wK8nM4gB6hJ1lD0fA",      "last_request_body": "{\"client\": \"ООО Ромашка\", \"amount\": 15000}"    },    "oauth_client_enabled": true,    "oauth_client": {      "client_id": "aB3dE5fG7hJ9kL1mN3pQ5rS7tU9vW1xY",      "client_secret_preview": "dGhpc19p...ZWNy",      "confidential": true,      "redirect_uris": [        "https://example.com/oauth/callback"      ],      "scopes": [        "messages:read",        "messages:create"      ]    },    "promo": {      "description": "Собирает сводку по задачам и присылает её в чат",      "published": true,      "promo_images": []    },    "permissions": {      "update_oauth_client": true,      "recreate_token": true,      "destroy": true    },    "access_token": "bm90X2FfcmVhbF90b2tlbg"  }}