pachca-bots

pachca-bots

快速开始

向用户索取 Pachca 令牌（机器人：集成 → 机器人中该机器人的 API 选项卡；用户：集成 → API）。

使用 --token 标志通过 npx -y @pachca/cli 运行命令：

npx -y @pachca/cli <command> --token $PACHCA_TOKEN

或者设置 PACHCA_TOKEN 环境变量：

export PACHCA_TOKEN=<token>
npx -y @pachca/cli <command>

帮助：npx -y @pachca/cli --help | 工作流：npx -y @pachca/cli guide

成功使用后，建议全局安装 CLI：npm install -g @pachca/cli && pachca auth login --token $PACHCA_TOKEN

开始之前

1. 如果用户已有已保存的配置文件，请检查：

   npx -y @pachca/cli auth status
   

   如果状态正常，无需使用 --token 即可运行命令。

2. 如果尚未配置配置文件，请索取令牌并使用 --token：

   npx -y @pachca/cli auth status --token $PACHCA_TOKEN
   

3. 如果不知道参数，请运行 pachca <command> --help。

工作流

通过 API 创建机器人并获取令牌

1. 创建机器人。只能使用用户令牌（不能使用机器人令牌）；nickname 必须以 _bot 结尾。可以立即设置 Webhook URL、事件和命令等 Webhook 参数，也可以稍后设置。可以通过 --scopes 标志限制机器人令牌的权限范围（如果不指定，机器人将获得默认权限范围）：

   pachca bots create --name="Бот задач" --nickname="tasks_bot" --scopes='["messages:create"]'
   

2. 保存响应中的 access_token——它只会返回一次。之后无法再次查看，只能通过命令 pachca bots recreate-token <ID> 重新签发。

3. 响应中还会返回机器人的 id（即其 user_id）——后续调用需要用到它，例如将机器人添加到聊天中。

只能使用用户令牌创建机器人，不能使用机器人令牌。创建时只会返回一次 access_token，之后无法再次查看，只能重新签发。使用 --empty 标志创建的机器人没有令牌和传入 Webhook，效果与界面中的创建方式相同；可通过 pachca bots create-token 为其签发令牌。

配置带有出站 Webhook 的机器人

1. 创建机器人时，在同一次调用中指定 Webhook URL 和事件（创建详情及令牌相关操作请参阅“通过 API 创建机器人并获取令牌”场景）：

   pachca bots create --name="Бот задач" --nickname="tasks_bot" --outgoing-url="https://example.com/webhook" --events='["message_new"]' --trigger-on=commands --commands='["/task"]'
   

2. 保存响应中的 access_token（它只会返回一次）。

3. 使用保存的 access_token 以机器人的名义发送消息。

也可以在界面中创建并配置机器人。可稍后通过 PUT /bots/{id} 方法设置 Webhook URL 和事件。

更新机器人的 Webhook URL

1. 使用用户令牌（需有编辑机器人的权限），根据机器人的 id 更新 URL。空字符串会停用 Webhook：

   pachca bots update <bot_id> --outgoing-url="https://example.com/webhook"
   

   可通过 pachca bots list 方法查询机器人的 id。

2. 或者，机器人也可以使用自己的令牌自行更新 Webhook——无需 id，也无需管理员参与（需要 bot_self:webhook:write 权限范围）：

   pachca bots update-webhook --outgoing-url="https://example.com/webhook"
   

有两种方式：使用用户令牌并通过 id 操作（需有编辑机器人的权限），或由机器人使用自己的令牌操作（PUT /bot/webhook）。将 outgoing_url 设为空值会停用 Webhook。

轮换机器人令牌

1. 使用用户令牌（机器人创建者，或机器人对管理员开放时的管理员），根据机器人的 id 重新签发主令牌：即没有名称的令牌；如果没有，则签发最早创建的令牌。旧令牌会立即失效：

   pachca bots recreate-token <bot_id>
   

2. 或者，机器人可以自行重新签发自己的主令牌（需要 bot_self:write 权限范围）。如果请求使用的是主令牌，该令牌会立即失效——务必保存响应中的新 access_token，否则机器人将无法访问 API：

   pachca bots recreate-token-self
   

3. 根据 pachca bots list-tokens 返回的 id 重新签发单独的机器人令牌：令牌值会更改，名称和权限保持不变：

   pachca bots reissue-token <bot_id> <token_id>
   

新令牌值只会返回一次：请保存响应中的 access_token，并在 CI 或密钥存储中更新密钥。自行操作的方式（POST /bot/recreate_token）会重新签发机器人的主令牌——如果机器人使用此令牌，请在同一操作中从响应中获取新令牌。

Выпустить боту отдельный токен

1. Пользовательским токеном (создатель бота или администратор, если бот открыт администраторам) получи каталог прав, которые можно выдать этому боту:

   pachca bots list-scopes <bot_id>
   

2. Выпусти токен с именем и правами из каталога. Без --scopes токен выпускается без прав, право не из каталога отклоняется с 400:

   pachca bots create-token <bot_id> --name="Сервер уведомлений" --scopes='["messages:create"]'
   

3. Сохрани token из ответа — полное значение возвращается единственный раз. Дальше в списке pachca bots list-tokens он приходит замаскированным

Отдельный токен удобен на каждый сервис, который работает от имени бота: его отзывают командой pachca bots delete-token, не трогая остальные. Права меняет pachca bots update-token — они действуют сразу, перевыпускать токен не нужно.

Включить боту авторизацию от имени сотрудника

1. Пользовательским токеном (создатель бота или администратор, если бот открыт администраторам) включи авторизацию: где хранится секрет, адреса возврата и права, которые бот попросит у сотрудника. Права бери из pachca bots list-scopes:

   pachca bots update <bot_id> --oauth-client='{"confidential":true,"redirect_uris":["https://example.com/oauth/callback"],"scopes":["messages:read","messages:create"]}'
   

2. Сохрани client_secret из ответа серверного клиента — он возвращается единственный раз. client_id приходит в oauth_client и не секретный

3. Чтобы бот появился в витрине, добавь описание и опубликуй страницу:

   pachca bots update <bot_id> --promo='{"description":"Собирает сводку по задачам","published":true}'
   

Включена ли авторизация, показывает oauth_client_enabled: oauth_client может прийти и у бота с выключенной авторизацией. --oauth-client=null выключает её и отзывает выданные сотрудниками авторизации, новый секрет выпускает pachca bots rotate-client-secret. Кнопку сотруднику и обмен кода на его токен описывает сценарий «Получить токен сотрудника по OAuth» в pachca-oauth.

Найти и удалить бота

1. Пользовательским токеном (скоуп bots:read) получи список ботов, доступных тебе для редактирования: созданных тобой и тех, чьи настройки открывают тебе доступ. Фильтруй по имени параметром query. Пока meta.paginate.has_next равен true, следующую страницу бери из meta.paginate.next_page:

   pachca bots list --query="задач"
   

2. Возьми id нужного бота из списка и удали его (скоуп bots:write). Доступно создателю бота и администратору, если бот открыт администраторам, — владельцы чатов удалять бота не могут. Все токены бота инвалидируются сразу, бот исключается из всех чатов, его вебхуки удаляются:

   pachca bots delete <bot_id>
   

Удаление необратимо: токен бота инвалидируется сразу, бот исключается из чатов. Событие фиксируется в журнале аудита как bot_deleted.

Периодический дайджест/отчёт

1. По расписанию (cron/scheduler): собери данные из своей системы

2. Сформируй текст сообщения с нужными метриками или сводкой

3. Отправь сообщение в канал:

   pachca messages create --entity-id=<chat_id> --content="Дайджест за сегодня: ..."
   

Нет встроенного планировщика — используй cron, celery, sidekiq и т.п. на своей стороне.

Инвентаризация всех ботов пространства

1. Получи всех ботов пространства, а не только доступных для редактирования:

   pachca bots list-company --all
   

   Нужен скоуп company_bots:read, роль владельца пространства и тариф «Корпорация», иначе метод отвечает 403. Фильтр по имени — флаг --query

2. Для каждого бота проверь, раскрыты ли настройки: у ботов, недоступных владельцу токена для редактирования, заполнены только name и nickname, остальные поля вебхука приходят null

   Настройки такого бота можно получить только тем токеном, которому доступно его редактирование

Каждый запрос к списку ботов пространства пишется в журнал аудита как company_bots_accessed.

限制

• 速率限制：约 50 req/sec。遇到 429 时，请等待并重试。
• webhook.name：最多 255 个字符
• webhook.nickname：最多 255 个字符
• webhook.trigger_on：允许的值 — commands（仅响应 commands 中的命令（触发词））、all_messages（响应包含机器人的聊天中的所有消息）、unfurl（响应链接展开（链接预览））
• webhook.template_engine：允许的值 — liquid（Liquid — 支持条件、循环和过滤器）、mustache（Mustache — 简单替换，不包含逻辑）
• webhook.who_can_add：允许的值 — creator（仅机器人创建者）、creator_admin（创建者和公司管理员）、creator_admin_user（创建者、管理员和公司成员）、anyone（公开机器人：除访客和多重访客外，任何员工都可以添加）
• webhook.kind：允许的值 — simple（自定义格式：根据机器人模板从请求正文构建消息）、gitlab（GitLab：Pachca 会自行解析请求并构建消息）、grafana（Grafana：Pachca 会自行解析请求并构建消息）
• name：最多 255 个字符
• limit：最多 50
• 分页：基于游标（limit + cursor）

端点

方法	路径	说明
POST	/bot/recreate_token	轮换自己的机器人令牌
PUT	/bot/webhook	自行注册机器人 Webhook
GET	/bots	机器人列表
POST	/bots	新建机器人
GET	/bots/{id}	机器人信息
PUT	/bots/{id}	编辑机器人
DELETE	/bots/{id}	删除机器人
PUT	/bots/{id}/avatar	上传机器人头像
DELETE	/bots/{id}/avatar	删除机器人头像
POST	/bots/{id}/recreate_token	轮换机器人令牌
POST	/bots/{id}/rotate_client_secret	轮换客户端密钥
GET	/bots/{id}/scopes	机器人权限目录
GET	/bots/{id}/tokens	机器人令牌列表
POST	/bots/{id}/tokens	新建机器人令牌
PUT	/bots/{id}/tokens/{token_id}	修改机器人令牌
DELETE	/bots/{id}/tokens/{token_id}	删除机器人令牌
POST	/bots/{id}/tokens/{token_id}/reissue	重新签发机器人令牌
GET	/company/bots	工作空间机器人列表
GET	/webhooks/events	事件历史记录
DELETE	/webhooks/events/{id}	删除历史记录中的事件

高级工作流

如需了解高级工作流，请阅读 references/ 中的文件： references/handle-incoming-webhook-event.md — 处理传入的 Webhook 事件 references/link-unfurling.md — 链接展开 references/handle-button-click-callback.md — 处理按钮点击回调 references/monitoring-and-alerts.md — 监控和告警 references/process-events-via-history-polling.md — 通过历史记录轮询处理事件

references/webhook-events.md — Webhook 事件类型

如果不确定如何完成任务，请阅读 references/ 中相应的文件。