GetMyBot 知識庫

REST API 與 Token

從自己的程式管理機器人:存取權杖種類、REST API 操作與請求範例。

本頁內容

REST API 讓你的程式透過 HTTP 存取 GetMyBot,例如讀取集合中的申請資料、建立反應或取得統計資料。若只在後台設定機器人,就不需要 API。整合時可先完成第一個請求,再到互動式 API 參考文件查看欄位。

程式需使用權杖驗證身分。機器人 API 權杖與個人存取權杖的用途不同。

機器人 API Token

在設定 → API Token 中建立。每個 Token 與特定機器人繫結,可用於呼叫其 REST 端點(反應、使用者、集合、統計等)。Token 僅在建立時顯示一次,請妥善保存;清單僅顯示名稱、遮罩及建立日期。請刪除不再使用的 Token。

個人存取 Token(PAT)

個人存取 Token(PAT,以 mbp_ 開頭)作用於帳號層級,用於自動化與整合。在個人後台建立;以 Authorization: Bearer mbp_… 標頭傳遞。Token 具有存取範圍(scopes)——資源:動作 格式的權限集合(例如 reactions:read、bots:write),* 代表完整存取。可設定有效期限,Token 本身以雜湊方式儲存。這是授予腳本有限存取權限而無需提供密碼的便利方式。

API 可存取的內容

透過 API 可存取與介面相同的資源:機器人及其設定、反應(含匯入/匯出)、訂閱者與標籤、集合與記錄、統計與請求記錄、群發。這讓你能在 GetMyBot 之上建構自訂儀表板、同步及自動化流程。

頻道與 WhatsApp

GetMyBot 是多頻道的(Telegram + WhatsApp + VK),機器人的頻道同樣可以透過 REST 管理。頻道和 WhatsApp 範本受 共用 scope bots:read / bots:write 控制——沒有單獨的頻道 scope。

  • GET /api/channels/capabilities — 頻道能力矩陣(工作階段端點,無需 PAT 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 參考文件。

CRM 連接

CRM 使用獨立的 crm:read、crm:write,integrations:* 無法取代它們。各路由還會檢查機器人的「反應」權限。

  • POST /api/bots/{botID}/crm/connections/amocrm/start(crm:write):送出 {"account_key":"acme.amocrm.ru"},再於瀏覽器開啟回傳的 redirect_url。每個帳號每分鐘最多三次。平台尚未設定 amoCRM OAuth 應用時回傳 503;Bitrix24 也有相同限制。
  • 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 工具。完整路由和提供者行為見 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|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|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/… 中的寄件網域與收件郵件路由。讀取需機器人存取權;建立、驗證和刪除還需「反應」權限。

consent-preview、validate、preview 雖不修改資料,仍使用 POST,因此會記入稽核。修改時傳入讀取到的 expected_revision;409 表示應重新讀取後再試。排程還需要 "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:有訂閱時先回傳含訂閱數的 409;提供 "confirm": true 後會使所有既有訂閱失效。
  • 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/* 也不接受安裝權杖。其獨立 OpenAPI 文件可免驗證從 GET /sdk/openapi.yaml 取得。

群發

群發只有 broadcasts:write,讀取清單、報告和收件者也需要這個 scope,無法發出唯讀群發權杖。所有路由還會檢查機器人的「反應」權限。

第二代群發包含內容、受眾和頻道:

  • 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 的 start_broadcast、get_broadcast、pause_broadcast、resume_broadcast、cancel_broadcast、list_content_broadcasts 和 get_content_broadcast_report 都使用 broadcasts:write,即使其中有唯讀操作。第二代草稿的建立、修改、收件者檢查、啟動、測試發送與封存只開放 REST;MCP 的暫停、繼續和取消僅適用於舊式反應群發。詳見群發。

行動裝置存取

平台提供行動應用程式,有獨立的授權機制(access 與 refresh Token)及機器人總覽儀表板,使用相同的後端服務。

API 參考文件

完整的互動式公開 API 參考文件位於 API 參考 頁面:列出所有可透過 PAT 存取的端點、參數、請求與回應 Schema、所需 scopes,以及現成的請求範例(curl、JavaScript、Python)。可直接在頁面上使用自己的 Token 進行試用。

漏斗與實驗

儲存的漏斗定義與報告使用 analytics:read / analytics:write,將群體儲存為區隔還需 segments:write。實驗的定義、生命週期、報告和群體使用 experiments:read / experiments:write。所有端點另需機器人的「分析」權限。經驗證的 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 參考文件、漏斗和實驗。

安全性

  • Token 僅顯示一次;請將其視為機密保管。
  • 機器人 Secret 及憑證以加密方式儲存。
  • 稽核依 HTTP 方法記錄經驗證的 POST、PUT、PATCH、DELETE;GET 不記錄。

Customer AI、場景分析、Playbooks 與 Meta

  • 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 須先對你的後台開啟;未開啟時 REST 與 MCP 都會拒絕請求。

延伸閱讀