GetMyBot 知识库

REST API 与令牌

从自己的程序管理机器人:两种访问令牌、REST API 的操作以及请求示例。

本页内容

REST API 允许程序通过 HTTP 访问 GetMyBot,例如读取集合中的申请、创建反应或获取统计。如果只在管理页面配置机器人,就无需使用 API。集成开发可从第一个请求开始,精确字段见交互式参考。

访问依靠作为程序密钥的令牌。机器人 API 令牌绑定特定机器人,个人令牌则用于选定账户空间内的自动化。两类令牌的能力不同。

机器人 API 令牌

在 设置 → API 令牌 中创建。每个令牌绑定到一个机器人,允许访问其 REST 端点(反应、用户、集合、统计等)。令牌仅在创建时显示一次——请妥善保存;列表只显示名称、掩码和创建日期。请及时删除多余的令牌。

个人访问令牌(PAT)

个人访问令牌(PAT,以 mbp_ 开头)在账户级别生效,用于自动化和集成。在个人中心创建;通过 Authorization: Bearer mbp_… 请求头传递。令牌具有访问范围(scopes)——一组 资源:操作 权限(例如 reactions:read、bots:write),* 表示完全访问。有效期可限制,令牌以哈希形式存储。这是在不暴露密码的情况下为脚本提供受限访问的便捷方式。

API 可访问的内容

通过 API 可访问与界面相同的实体:机器人及其设置、反应(包括导入/导出)、订阅者与标签、集合与记录、统计与请求日志、群发。这允许你在 GetMyBot 之上构建自定义面板、同步和自动化。

渠道与 WhatsApp

Telegram、WhatsApp 和 VK 连接也可通过 REST 管理。读取渠道和 WhatsApp 模板需 bots:read,更改需 bots:write,没有单独的渠道 scope。

  • GET /api/channels/capabilities(bots:read)— 渠道能力矩阵;网站会话无需 scope。
  • GET /api/bots/{botID}/channels(bots:read)— 列出机器人的渠道。
  • POST /api/bots/{botID}/channels(bots:write)— 连接 WhatsApp 或 VK 渠道。
  • DELETE /api/bots/{botID}/channels/{channelID}(bots:write)— 断开渠道。
  • GET /api/bots/{botID}/channels/{channelID}/templates(bots:read)— 渠道的 WhatsApp 模板目录。
  • POST /api/bots/{botID}/channels/{channelID}/templates(bots:write)— 创建模板并提交给 Meta 审核。
  • POST /api/bots/{botID}/channels/{channelID}/templates/sync(bots:write)— 从 Meta 重新同步目录。
  • PUT /api/bots/{botID}/channels/{channelID}/templates/{templateID}(bots:write)— 编辑模板。
  • DELETE /api/bots/{botID}/channels/{channelID}/templates/{templateID}(bots:write)— 删除模板。
  • POST /api/bots/{botID}/channels/{channelID}/templates/media(bots:write)— 上传头部媒体示例(图片/视频/文档)。

请求与响应结构、参数和示例见 API 参考。渠道和模板的使用说明见 WhatsApp。

CRM 连接

CRM 使用独立的 crm:read 和 crm:write scope,integrations:* 不能代替。每个路由还检查机器人的“反应”权限。连接方式取决于服务商:

  • POST /api/bots/{botID}/crm/connections/amocrm/start(crm:write):发送 {"account_key":"acme.amocrm.ru"},取得需在浏览器打开的 redirect_url。每个账户每分钟最多启动三次。若平台尚未配置 amoCRM OAuth 应用,接口返回 503;Bitrix24 因同样原因返回 503。
  • GET /api/integrations/crm/{provider}/callback:浏览器重定向目标,无需令牌;授权依靠启动时生成的五分钟有效的一次性状态。响应只返回安全摘要,不返回访问凭据。
  • POST /api/bots/{botID}/crm/connections/retailcrm(crm:write):用 API 密钥连接。
  • POST /api/bots/{botID}/crm/connections/ozmacrm(crm:write):用 OIDC 凭据、用户名和实体配置连接。

另有字段与漏斗发现、映射版本、预览、首次同步、重新核对、操作与任务、冲突处理,以及断开连接的 DELETE /api/bots/{botID}/crm/connections/{connectionID}。订阅者下还有 CRM 状态、手动同步和导出对话三种动作,路径为 /api/bots/{botID}/subscribers/{subscriberID}/crm/…,需 subscribers:* scope 和“对话”权限。MCP 仅提供六种只读 CRM 工具,见 MCP。完整路由、scope 和服务商行为见 CRM 集成。

内容、邮件群发与弹窗

内容功能有独立 scope。以下接口还检查机器人的“反应”权限,因此令牌无法越过其账户的权限边界:

  • content:read / content:write:内容文档与模板。GET|POST /api/bots/{botID}/content、GET /api/bots/{botID}/content/{documentID}、PATCH /api/bots/{botID}/content/{documentID}/draft、POST /api/bots/{botID}/content/{documentID}/publish|clone|archive|test-send、POST /api/bots/{botID}/content/{documentID}/validate|preview、GET /api/bots/{botID}/content/test-recipients、GET|POST /api/bots/{botID}/content-templates、DELETE /api/bots/{botID}/content-templates/{templateID}。
  • email_campaigns:read / email_campaigns:write:邮件群发和报告。GET|POST /api/bots/{botID}/email-campaigns、GET|PATCH /api/bots/{botID}/email-campaigns/{campaignID}、GET /api/bots/{botID}/email-campaigns/{campaignID}/report|recipients|links、POST /api/bots/{botID}/email-campaigns/{campaignID}/consent-preview、POST /api/bots/{botID}/email-campaigns/{campaignID}/test-send|schedule|clone|pause|resume|cancel|archive。
  • popups:read / popups:write:GET|POST /api/bots/{botID}/popups、PATCH|DELETE /api/bots/{botID}/popups/{popupID}、GET /api/bots/{botID}/popups/{popupID}/stats|experiment、POST /api/bots/{botID}/popups/preflight。
  • settings:read / settings:write:/api/bots/{botID}/email/… 下的发信域名和收信路由。发信域名是机器人设置,因而使用设置 scope。读取只需有机器人访问权;创建、验证及删除还需“反应”权限。

consent-preview、validate 和 preview 即使不修改数据,也使用 POST,并像其他已授权 POST 一样记入审计。修改操作采用乐观锁:传入读取时得到的 expected_revision;409 表示应重新读取后重试,而非传输故障。POST /api/bots/{botID}/email-campaigns/{campaignID}/schedule 还要求 "confirm": true;群发未就绪时返回含完整收件人检查结果的 422。公开的跟踪、退订和服务商 webhook(/e/t/…、/u/…、/esp/{provider}/webhook、/esp/{provider}/inbound)不属于令牌 API,详见邮件群发。

浏览器推送与客户端 SDK

两类功能各有独立的读写 scope,并检查机器人权限:读取需“分析”权限,写入需“反应”权限。所有修改均记入审计。

浏览器推送使用 web_push:read / web_push:write:

  • GET /api/bots/{botID}/web-push:清理过的配置,包括 VAPID 公钥、联系地址、允许的跳转 origin 和免打扰时段,绝不返回私钥。
  • GET /api/bots/{botID}/web-push/subscriptions:近期订阅、同意状态、浏览器类型、语言和时区,绝不返回推送服务地址或加密密钥。
  • GET /api/bots/{botID}/web-push/report:订阅与回执计数。
  • POST /api/bots/{botID}/web-push/enable:首次调用生成 VAPID 密钥对,之后作为幂等的设置更新。
  • PATCH /api/bots/{botID}/web-push:修改联系地址、跳转 origin、免打扰时段和启用状态。
  • POST /api/bots/{botID}/web-push/rotate-keys:有活跃订阅时,未传 "confirm": true 会返回 409 和订阅数量;确认后所有现有订阅失效。
  • POST /api/bots/{botID}/web-push/test:向一个订阅测试发送一条消息,链接到已发布的 Push 类型文档。常规发送使用群发或活动。

客户端 SDK使用 customer_sdk:read / customer_sdk:write:

  • GET /api/bots/{botID}/customer-sdk:清理过的项目配置,包括项目密钥、区域、允许的应用、身份密钥版本,以及轮换期间旧密钥的失效时间。
  • GET /api/bots/{botID}/customer-sdk/installations:最多 200 个近期安装。
  • GET /api/bots/{botID}/customer-sdk/report:安装及推送令牌计数。
  • POST /api/bots/{botID}/customer-sdk/enable:创建项目并仅在首次返回身份密钥,之后是幂等设置更新。若部署未配置项目密钥签名密钥,返回 503。
  • PATCH /api/bots/{botID}/customer-sdk:允许的应用列表及启用状态。
  • POST /api/bots/{botID}/customer-sdk/rotate-secret:返回新身份密钥,旧密钥再有效一天。
  • DELETE /api/bots/{botID}/customer-sdk/installations/{installationID}:撤销一台设备。

SDK 面向客户端的 /sdk/v1/* 不属于这个 API。它使用安装令牌和身份时期授权,不接受个人令牌;相应地,/api/* 不接受安装令牌。服务器在无需授权的 GET /sdk/openapi.yaml 单独发布其 OpenAPI 文档。

群发

群发只有 broadcasts:write 一个 scope,没有单独的只读 scope。读取列表、报告及分页收件人也需要 broadcasts:write;无法发放只读群发令牌。所有路由还检查机器人的“反应”权限。

第二代群发同时管理内容、受众和渠道:

  • GET /api/bots/{botID}/broadcasts:列表;?archived=true 加入归档项。
  • POST /api/bots/{botID}/broadcasts:创建草稿。
  • PATCH /api/bots/{botID}/broadcasts/{broadcastID}:修改草稿。
  • POST /api/bots/{botID}/broadcasts/{broadcastID}/preflight:检查收件人,不发送,但因使用 POST 而记入审计。
  • POST /api/bots/{botID}/broadcasts/{broadcastID}/schedule:启动。
  • POST /api/bots/{botID}/broadcasts/{broadcastID}/test-send:向一个已确认联系人测试发送。
  • POST /api/bots/{botID}/broadcasts/{broadcastID}/archive:归档。
  • GET /api/bots/{botID}/broadcasts/{broadcastID}/report:按渠道的报告。
  • GET /api/bots/{botID}/broadcasts/{broadcastID}/recipients:收件人,使用 limit 和 cursor 分页。

旧版按反应发送的群发仍使用相同基础路径,通过 POST /api/bots/{botID}/reactions/{reactionID}/broadcast 和请求体 {"paid":false,"labels":["vip"]} 启动;只有这里能按标签缩小群发范围。两种群发共用 GET /api/bots/{botID}/broadcasts/{broadcastID} 和 POST /api/bots/{botID}/broadcasts/{broadcastID}/pause|resume|cancel。处理器先查第二代群发,再查旧版,因此请求体与响应取决于 ID 类型:第二代要求 {"expected_revision":N} 并返回完整群发;旧版忽略请求体,返回 {"status":"pausing"}、{"status":"resuming"} 或 {"status":"canceled"}。

请求体严格校验:未知字段返回 400。修改时传入已读取的 expected_revision;409 表示版本冲突,应重新读取后重试。schedule 还要求 "confirm": true,否则返回 400。其他常见状态:402 表示机器人所有者套餐不含群发;403 表示该机器人未启用付费群发;409 也可能表示内容未发布、分组未重新计算、实验未开始或受众为空;422 表示没有内容或某渠道校验失败;429 表示测试发送过于频繁。

MCP 用同一个 scope 提供 start_broadcast、get_broadcast、pause_broadcast、resume_broadcast、cancel_broadcast、list_content_broadcasts 和 get_content_broadcast_report。后两个及 get_broadcast 虽只读,仍需 broadcasts:write。第二代的草稿创建与修改、收件人检查、启动、测试发送和归档只在 REST 提供;MCP 的暂停、恢复、取消仅适用于旧版按反应群发。详见群发。

移动端访问

平台有移动端应用,拥有独立的授权(access 和 refresh 令牌)及机器人汇总仪表盘——使用同一后端。

API 参考

完整的公开 API 交互式参考可在 API 参考 页面查看:列出了所有支持 PAT 的端点、参数、请求与响应 Schema、所需 scopes 及现成示例(curl、JavaScript、Python)。可直接在页面上用自己的令牌执行测试请求。

漏斗与实验

已保存漏斗的定义和报告使用 analytics:read / analytics:write;将用户群保存为分组还需要 segments:write。实验定义、生命周期操作、报告和用户群使用 experiments:read / experiments:write。这些接口都检查机器人的“分析”权限。审计取决于 HTTP 方法:对已授权持有人的所有 POST、PUT、PATCH、DELETE 都记入审计,包括语义上只读但通过 POST 提交的报告、查询和用户群请求;GET 读取和列表不记入审计。

报告须传入有界的 UTC RFC3339 时间区间。漏斗和实验最多支持 366 天。实验收入包含整数 minor 和 ISO 4217 currency,不要在客户端合并不同货币。

curl "$BASE_URL/api/bots/$BOT_ID/funnels?limit=50&cursor=$CURSOR" \
  -H "Authorization: Bearer $PAT"

把服务器返回的 next 游标原样传回。无效游标或请求体返回 400;不可访问的机器人资源或指定的实验版本返回 404;修改时版本过期或选择胜者冲突返回 409。完整请求与响应结构见 API 参考以及漏斗和实验指南。

安全性

  • 令牌仅显示一次;请像保管密钥一样保存。
  • 机器人与凭据的密钥以加密形式存储。
  • 审计按 HTTP 方法记录已授权的 POST、PUT、PATCH、DELETE;GET 读取不记入审计。

Customer AI、场景分析、Playbooks 与 Meta

以下功能可通过 AI 辅助自动化。API 中的名称保持英文:

  • Managed AI:POST /api/v1/ai/responses(managed_ai:invoke)和 GET /api/v1/ai/usage(managed_ai:usage:read)分别用于调用模型和读取用量。配置为 fast、balanced、quality;提供商为 auto、openai、anthropic、deepseek。调用必须带 Idempotency-Key。自己的提供商密钥失败时不会自动切换到付费 Managed AI。
  • Copilot:在 /api/reactions/{rootID}/copilot/proposals 创建反应修改提案;通过 /api/copilot/proposals/{proposalID} 读取、验证、模拟、应用或拒绝。应用会创建草稿,不会发布。
  • Flow Intelligence:查看反应路径数据、执行样例和分析规则;/api/bots/{botID}/flow-intelligence/* 提供设置及有界时间范围内的重新计算。
  • Explainable Replay:读取和模拟执行轨迹,制作已清除敏感信息的回归样例并检查重放结果;不会向代理暴露受保护材料。
  • Vertical Playbooks:/api/playbooks/catalog 中的现成场景,以及恢复中断的设置、预检、安装、升级和结果指标(KPI)。
  • Outcome onboarding:按目标逐步完成初始配置,接口为 POST|PATCH /api/onboarding/session 和 POST /api/onboarding/session/complete。
  • Messenger 与 Instagram:/api/meta/connections 返回在浏览器中进行 Meta 授权的地址,随后可检查、选择和连接该账户空间中的页面和账号;响应不返回秘密令牌。

提供商密钥、路由、价格和结算核对仅供超级管理员管理,用户 API 和 MCP 都不能访问。Copilot、Flow Intelligence、Explainable Replay 和 Vertical Playbooks 必须在账户空间启用;未启用或尚未提供时请求会被拒绝,MCP 同样受此限制。

下一步