Back to Details

pachca-bots

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

pachca-bots

pachca-bots

Base URL: 
https://api.pachca.com/api/shared/v1
Авторизация: 
Authorization: Bearer <ACCESS_TOKEN>
Токен: бот (Автоматизации → Интеграции → API) или пользователь (Автоматизации → API).
基础URL: 
https://api.pachca.com/api/shared/v1
授权方式: 
Authorization: Bearer <ACCESS_TOKEN>
令牌来源：机器人（自动化 → 集成 → API）或用户（自动化 → API）。

Когда использовать

适用场景

  • настроить бота
  • вебхук
  • webhook
  • обработать событие
  • подпись вебхука
  • нажатие кнопки
  • callback
  • дайджест
  • алерт
  • polling
  • unfurl
  • развернуть ссылку
  • link preview
  • 配置机器人
  • Webhook
  • webhook
  • 处理事件
  • Webhook签名
  • 按钮点击
  • callback
  • 摘要
  • 告警
  • polling
  • unfurl
  • 展开链接
  • link preview

Когда НЕ использовать

不适用场景

  • получить профиль, мой профиль, установить статус → pachca-profile
  • найти сотрудника, создать пользователя, список сотрудников → pachca-users
  • создать канал, создать беседу, создать чат → pachca-chats
  • отправить сообщение, ответить в тред, прикрепить файл → pachca-messages
  • показать форму, интерактивная форма, модальное окно → pachca-forms
  • создать задачу, список задач, напоминание → pachca-tasks
  • аудит, журнал событий, безопасность → pachca-security
  • 获取个人资料、我的资料、设置状态 → pachca-profile
  • 查找员工、创建用户、员工列表 → pachca-users
  • 创建频道、创建群聊、创建聊天 → pachca-chats
  • 发送消息、回复线程、附加文件 → pachca-messages
  • 显示表单、交互式表单、模态窗口 → pachca-forms
  • 创建任务、任务列表、提醒 → pachca-tasks
  • 审计、事件日志、安全 → pachca-security

Пошаговые сценарии

分步场景教程

Настроить бота с исходящим вебхуком

配置带出站Webhook的机器人

  1. Создай бота в интерфейсе Пачки: Автоматизации → Интеграции → Webhook
  2. Получи 
    access_token
    бота во вкладке «API» настроек бота
  3. Укажи Webhook URL для получения событий
  4. Выбери типы событий: новые сообщения, реакции, кнопки, участники
Бот создаётся через UI, не через API. Единственный эндпоинт для ботов — PUT /bots/{id} (обновление webhook URL). API используется для отправки сообщений от имени бота.
  1. 在Pachca界面中创建机器人：自动化 → 集成 → Webhook
  2. 在机器人设置的「API」标签页获取机器人的
    access_token
  3. 指定用于接收事件的Webhook URL
  4. 选择事件类型：新消息、反应、按钮、成员变动
机器人通过UI创建，而非API。机器人相关的唯一API端点是PUT /bots/{id}（更新webhook URL）。API用于以机器人名义发送消息。

Обработать входящий вебхук-событие

处理入站Webhook事件

  1. Получи POST-запрос на свой Webhook URL
  2. Проверь подпись (Signing secret) для безопасности
  3. Проверь 
    webhook_timestamp
    — должен быть в пределах 1 минуты
  4. Разбери JSON: тип события, данные
  5. Для полной информации сделай запрос к API: GET /messages/{id} — особенно важно для получения вложений (
    files[]
    ), которых нет в вебхуке
Вебхук содержит минимум данных — файлы (
files
) в нём отсутствуют. Если сообщение может содержать вложения, всегда запрашивай GET /messages/{id}.
  1. 在你的Webhook URL上接收POST请求
  2. 验证签名（Signing secret）以确保安全
  3. 验证
    webhook_timestamp
    — 必须在1分钟内
  4. 解析JSON：事件类型、数据
  5. 如需完整信息，调用API接口：GET /messages/{id} — 对于获取附件（
    files[]
    ）尤为重要，因为Webhook中不包含附件信息
Webhook仅包含最少数据 — 其中没有文件（
files
）。如果消息可能包含附件，请务必调用GET /messages/{id}。

Разворачивание ссылок (unfurling)

链接展开（unfurling）

  1. Создай специального Unfurl-бота и укажи отслеживаемые домены в его настройках
  2. При появлении ссылки бот получает вебхук 
    "event": "link_shared"
    с массивом 
    links
    (
    url
    + 
    domain
    ) и 
    message_id
  3. Извлеки данные из своей системы по URL из 
    links
  4. Отправь POST /messages/{id}/link_previews с превью-данными
bash
curl "https://api.pachca.com/api/shared/v1/messages/56431/link_previews" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"link_previews":{"https://example.com/article":{"title":"Заголовок статьи","description":"Краткое описание","image_url":"https://example.com/img.png"}}}'
Эндпоинт привязан к конкретному сообщению. Необходим специальный Unfurl-бот с указанными доменами.
  1. 创建专用的Unfurl机器人，并在其设置中指定要监控的域名
  2. 当出现链接时，机器人会收到
    "event": "link_shared"
    的Webhook，其中包含
    links
    数组（
    url
    + 
    domain
    ）和
    message_id
  3. 根据
    links
    中的URL从你的系统中提取数据
  4. 调用POST /messages/{id}/link_previews接口发送预览数据
bash
curl "https://api.pachca.com/api/shared/v1/messages/56431/link_previews" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"link_previews":{"https://example.com/article":{"title":"文章标题","description":"简短描述","image_url":"https://example.com/img.png"}}}'
该端点绑定到特定消息。需要使用指定了域名的专用Unfurl机器人。

Обработать нажатие кнопки (callback)

处理按钮点击（callback）

  1. Получи вебхук с 
    "event": "message_button_clicked"
    — в payload: 
    data
    (из кнопки), 
    user_id
    , 
    message_id
  2. Выполни нужное действие (запись в БД, запрос к API и т.д.)
  3. Ответь пользователю: POST /messages с 
    "entity_type": "user"
    , 
    "entity_id": user_id
    из вебхука
  4. Опционально: обнови исходное сообщение через PUT /messages/{id} — чтобы убрать кнопки передай 
    "buttons": []
    , чтобы изменить текст — передай 
    "content"
Кнопка с 
data
отправляет событие на вебхук. Кнопка с 
url
— открывает ссылку (вебхука не будет).
  1. 接收包含
    "event": "message_button_clicked"
    的Webhook — 负载中包含：
    data
    （来自按钮）、
    user_id
    、
    message_id
  2. 执行所需操作（写入数据库、调用API等）
  3. 回复用户：调用POST /messages接口，指定
    "entity_type": "user"
    和Webhook中的
    "entity_id": user_id
  4. 可选操作：通过PUT /messages/{id}更新原消息 — 若要移除按钮，传递
    "buttons": []
    ；若要修改文本，传递
    "content"
带
data
的按钮会向Webhook发送事件。带
url
的按钮会直接打开链接（不会触发Webhook）。

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

定期摘要/报告

  1. По расписанию (cron/scheduler): собери данные из своей системы
  2. Сформируй текст сообщения с нужными метриками или сводкой
  3. POST /messages с 
    "entity_id": chat_id
    нужного канала
Нет встроенного планировщика — используй cron, celery, sidekiq и т.п. на своей стороне.
  1. 按计划（cron/调度器）：从你的系统中收集数据
  2. 生成包含所需指标或摘要的消息文本
  3. 调用POST /messages接口，指定目标频道的
    "entity_id": chat_id
平台无内置调度器 — 请在你的系统中使用cron、celery、sidekiq等工具。

Мониторинг и алерты

监控与告警

  1. Внешняя система (CI, мониторинг, сервис) обнаруживает событие (ошибка, деплой, порог метрики)
  2. Делает POST запрос к твоему боту или напрямую вызывает Pachca API
  3. POST /messages в канал алертов с описанием события и кнопками «Взять в работу» / «Игнорировать»
  4. При нажатии кнопки — обработай callback и обнови статус алерта
  1. 外部系统（CI、监控、服务）检测到事件（错误、部署、指标阈值触发）
  2. 向你的机器人发送POST请求，或直接调用Pachca API
  3. 向告警频道发送POST /messages请求，包含事件描述和「接手处理」/「忽略」按钮
  4. 点击按钮时 — 处理回调并更新告警状态

Обработка событий через историю (polling)

通过历史记录处理事件（polling）

  1. В настройках бота включи «Сохранять историю событий» (вкладка «Исходящий webhook»). Webhook URL указывать не обязательно.
  2. По расписанию или по запросу: GET /webhooks/events — получи накопленные события с пагинацией (
    limit
    , 
    cursor
    )
  3. Обработай каждое событие (тот же формат payload, что и в real-time вебхуке)
  4. После обработки: DELETE /webhooks/events/{id} — удали событие, чтобы не обработать повторно
bash
curl "https://api.pachca.com/api/shared/v1/webhooks/events?limit=50" \
  -H "Authorization: Bearer $TOKEN"
Polling — альтернатива real-time вебхуку, если у бота нет публичного URL или нужна отложенная обработка. Подходит для batch-сценариев, скриптов, serverless-функций по расписанию.
  1. 在机器人设置中启用「保存事件历史」（「出站webhook」标签页）。无需指定Webhook URL。
  2. 按计划或按需调用：GET /webhooks/events — 获取带分页的累积事件（
    limit
    , 
    cursor
    ）
  3. 处理每个事件（负载格式与实时Webhook一致）
  4. 处理完成后：调用DELETE /webhooks/events/{id} — 删除事件，避免重复处理
bash
curl "https://api.pachca.com/api/shared/v1/webhooks/events?limit=50" \
  -H "Authorization: Bearer $TOKEN"
轮询是实时Webhook的替代方案，适用于机器人无公网URL或需要延迟处理的场景。适合批量场景、脚本、按计划运行的无服务器函数。

Обработка ошибок

错误处理

КодПричинаЧто делать
422Неверные параметрыПроверь обязательные поля, типы данных, допустимые значения enum
429Rate limitПодожди и повтори. Лимит: ~50 req/sec, сообщения ~4 req/sec
403Нет доступаНедостаточно скоупов (
insufficient_scope
), бот не в чате, или endpoint только для админов/владельцев
404Не найденоНеверный id. Проверь что сущность существует
401Не авторизованПроверь токен в заголовке Authorization
代码原因处理方式
422参数错误检查必填字段、数据类型、枚举值的合法范围
429请求频率超限等待后重试。限制：约50请求/秒，消息类约4请求/秒
403无权限权限范围不足（
insufficient_scope
）、机器人不在聊天中，或该端点仅对管理员/所有者开放
404未找到ID错误。检查实体是否存在
401未授权检查Authorization头中的令牌

Доступные операции

可用操作

Редактирование бота

编辑机器人

PUT /bots/{id}
скоуп: 
bots:write
json
{
  "bot": {
    "webhook": {
      "outgoing_url": "https://www.website.com/tasks/new"
    }
  }
}
PUT /bots/{id}
权限范围: 
bots:write
json
{
  "bot": {
    "webhook": {
      "outgoing_url": "https://www.website.com/tasks/new"
    }
  }
}

Unfurl (разворачивание ссылок)

链接展开（Unfurl）

POST /messages/{id}/link_previews
скоуп: 
link_previews:write
json
{
  "link_previews": {}
}
POST /messages/{id}/link_previews
权限范围: 
link_previews:write
json
{
  "link_previews": {}
}

История событий

事件历史

GET /webhooks/events
скоуп: 
webhooks:events:read
GET /webhooks/events
权限范围: 
webhooks:events:read

Удаление события

删除事件

DELETE /webhooks/events/{id}
скоуп: 
webhooks:events:delete
DELETE /webhooks/events/{id}
权限范围: 
webhooks:events:delete

Ограничения и gotchas

限制与注意事项

  • limit
    : максимум 50
  • Пагинация: cursor-based (limit + cursor), НЕ page-based
  • limit
    : 最大为50
  • 分页方式：基于cursor（limit + cursor），而非基于页码

Подробнее

更多详情

см. references/endpoints.md
请查看 references/endpoints.md