Cơ sở kiến thức GetMyBot

REST API và token

Cách điều khiển bot từ chương trình của bạn: các loại token, thao tác REST API và ví dụ yêu cầu.

Trên trang này

REST API cho phép chương trình của bạn gọi GetMyBot qua HTTP, chẳng hạn đọc yêu cầu trong bộ sưu tập, tạo phản ứng hoặc lấy thống kê. Nếu chỉ cấu hình bot trong giao diện quản lý, bạn không cần API. Để tích hợp, bắt đầu với yêu cầu đầu tiên, sau đó tra trường cụ thể trong tài liệu API tương tác.

Quyền truy cập dùng token, khóa bí mật của chương trình. Có token gắn với một bot và token cá nhân để tự động hóa trong phạm vi tài khoản đã chọn; quyền của hai loại khác nhau.

API token của bot

Tạo tại Cài đặt → API token. Mỗi token gắn với một bot và cho phép gọi endpoint REST của bot đó: phản ứng, người dùng, bộ sưu tập, thống kê và các mục khác. Token chỉ hiển thị một lần khi tạo; hãy lưu an toàn. Danh sách sau đó chỉ hiện tên, phần che và ngày tạo. Xóa token không còn dùng.

Token truy cập cá nhân (PAT)

PAT bắt đầu bằng mbp_, hoạt động ở cấp tài khoản, dùng cho tự động hóa và tích hợp. Tạo trong tài khoản cá nhân rồi gửi qua header Authorization: Bearer mbp_…. Mỗi PAT có scope, tức nhóm quyền dạng resource:action, ví dụ reactions:read và bots:write; * là toàn quyền. Token có thời hạn và được lưu dưới dạng hash. Nhờ vậy, script có thể nhận đúng quyền cần thiết mà không cần mật khẩu của bạn.

Có thể làm gì qua API

API cung cấp các đối tượng như trong giao diện: bot và cài đặt, phản ứng (kể cả nhập/xuất), người đăng ký và nhãn, bộ sưu tập và bản ghi, thống kê và nhật ký yêu cầu, các đợt gửi hàng loạt. Bạn có thể xây trang quản lý riêng, đồng bộ dữ liệu và tự động hóa.

Kênh và WhatsApp

Có thể quản lý kết nối Telegram, WhatsApp và VK qua REST. Đọc kênh và mẫu WhatsApp cần bots:read, thay đổi cần bots:write; không có scope chỉ dành riêng cho kênh.

  • GET /api/channels/capabilities (bots:read): khả năng từng kênh; phiên web hoạt động không cần scope.
  • GET /api/bots/{botID}/channels (bots:read): danh sách kênh của bot.
  • POST /api/bots/{botID}/channels (bots:write): kết nối WhatsApp hoặc VK.
  • DELETE /api/bots/{botID}/channels/{channelID} (bots:write): ngắt kênh.
  • GET /api/bots/{botID}/channels/{channelID}/templates (bots:read): danh mục mẫu WhatsApp.
  • POST /api/bots/{botID}/channels/{channelID}/templates (bots:write): tạo mẫu và gửi Meta xét duyệt.
  • POST /api/bots/{botID}/channels/{channelID}/templates/sync (bots:write): đồng bộ lại từ Meta.
  • PUT /api/bots/{botID}/channels/{channelID}/templates/{templateID} (bots:write): sửa mẫu.
  • DELETE /api/bots/{botID}/channels/{channelID}/templates/{templateID} (bots:write): xóa mẫu.
  • POST /api/bots/{botID}/channels/{channelID}/templates/media (bots:write): tải ảnh, video hoặc tài liệu mẫu cho phần đầu.

Sơ đồ, tham số và ví dụ ở Tài liệu API; cách dùng kênh và mẫu ở WhatsApp.

Kết nối CRM

CRM dùng scope riêng crm:read và crm:write; integrations:* không thay thế chúng. Mỗi endpoint còn kiểm tra quyền Phản ứng của bot.

  • POST /api/bots/{botID}/crm/connections/amocrm/start (crm:write): gửi {"account_key": "acme.amocrm.ru"}, nhận redirect_url để mở trong trình duyệt. Tối đa ba lần khởi tạo mỗi phút cho một tài khoản. Khi ứng dụng OAuth amoCRM chưa được cấu hình trên nền tảng, endpoint trả 503. Bitrix24 cũng trả 503 vì lý do tương tự.
  • GET /api/integrations/crm/{provider}/callback: đích chuyển hướng của trình duyệt. Không cần token: xác thực bằng trạng thái dùng một lần có hiệu lực 5 phút, được cấp khi bắt đầu. Kết quả là bản tóm tắt an toàn, không có bí mật kết nối.
  • POST /api/bots/{botID}/crm/connections/retailcrm (crm:write): kết nối bằng API key.
  • POST /api/bots/{botID}/crm/connections/ozmacrm (crm:write): kết nối bằng thông tin OIDC, đăng nhập và cấu hình entity.

Còn có endpoint để khám phá trường và pipeline, phiên bản mapping, xem trước, đồng bộ lần đầu, đối chiếu lại, thao tác và tác vụ, giải quyết xung đột, cùng DELETE /api/bots/{botID}/crm/connections/{connectionID} để ngắt kết nối. Ba thao tác theo người đăng ký (trạng thái CRM, đồng bộ thủ công, xuất hội thoại) nằm dưới /api/bots/{botID}/subscribers/{subscriberID}/crm/…, cần scope subscribers:* và quyền Hội thoại.

Sáu công cụ MCP chỉ đọc mô phỏng các thao tác đọc CRM, xem MCP. Bảng endpoint, scope và hành vi nhà cung cấp ở Tích hợp CRM.

Nội dung, chiến dịch email và pop-up

Các nhóm này có scope riêng và còn kiểm tra quyền Phản ứng của bot, nên token không vượt ra ngoài tài khoản của mình.

  • content:read / content:write: tài liệu và mẫu nội dung: 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 và DELETE /api/bots/{botID}/content-templates/{templateID}.
  • email_campaigns:read / email_campaigns:write: chiến dịch và báo cáo: 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 và 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 và POST /api/bots/{botID}/popups/preflight.
  • settings:read / settings:write: tên miền gửi và tuyến email đến dưới /api/bots/{botID}/email/…. Tên miền gửi là cài đặt bot nên dùng scope cài đặt, không có scope riêng. Đọc chỉ cần quyền vào bot; tạo, kiểm tra và xóa còn cần quyền Phản ứng.

consent-preview, validate và preview dùng phương thức POST dù không thay đổi dữ liệu, nên vẫn có bản ghi kiểm toán. Khi sửa, gửi expected_revision đã đọc; 409 nghĩa là cần tải lại và thử lại. Lên lịch bằng POST /api/bots/{botID}/email-campaigns/{campaignID}/schedule còn cần "confirm": true; nếu danh sách người nhận chưa sẵn sàng, endpoint trả 422 kèm kết quả kiểm tra đầy đủ.

Endpoint công khai dùng để theo dõi, hủy đăng ký hoặc nhận webhook của nhà cung cấp (/e/t/…, /u/…, /esp/{provider}/webhook, /esp/{provider}/inbound) không thuộc API theo token. Xem Chiến dịch email.

Web Push và SDK khách hàng

Mỗi nhóm có scope đọc/ghi riêng. Đọc cần quyền Phân tích của bot, ghi cần Phản ứng; mọi thay đổi được ghi vào nhật ký kiểm toán.

Web Push dùng web_push:read / web_push:write:

  • GET /api/bots/{botID}/web-push: cấu hình an toàn gồm khóa VAPID công khai, liên hệ, origin được phép và giờ im lặng; không trả khóa riêng.
  • GET /api/bots/{botID}/web-push/subscriptions: đăng ký gần đây với trạng thái đồng ý, họ trình duyệt, ngôn ngữ và múi giờ; không trả endpoint push hoặc khóa mã hóa.
  • GET /api/bots/{botID}/web-push/report: số đăng ký và biên nhận.
  • POST /api/bots/{botID}/web-push/enable: lần đầu tạo cặp khóa VAPID, các lần sau cập nhật cấu hình theo cách không tạo trùng.
  • PATCH /api/bots/{botID}/web-push: sửa liên hệ, origin, giờ im lặng và trạng thái bật.
  • POST /api/bots/{botID}/web-push/rotate-keys: trả 409 cùng số đăng ký còn hiệu lực nếu chưa có "confirm": true; xác nhận sẽ vô hiệu hóa toàn bộ đăng ký cũ.
  • POST /api/bots/{botID}/web-push/test: gửi thử một tin đến một đăng ký, có liên kết đến tài liệu Push đã xuất bản. Gửi thông thường qua gửi hàng loạt hoặc chiến dịch.

SDK khách hàng dùng customer_sdk:read / customer_sdk:write:

  • GET /api/bots/{botID}/customer-sdk: dự án an toàn gồm khóa dự án, vùng, danh sách ứng dụng được phép, phiên bản bí mật định danh và thời điểm bí mật cũ hết hạn trong lúc xoay vòng.
  • GET /api/bots/{botID}/customer-sdk/installations: tối đa 200 bản cài gần đây.
  • GET /api/bots/{botID}/customer-sdk/report: số bản cài và push token.
  • POST /api/bots/{botID}/customer-sdk/enable: tạo dự án, trả bí mật định danh một lần; lần sau là cập nhật không tạo trùng. Nếu nơi triển khai chưa có bí mật ký khóa dự án, trả 503.
  • PATCH /api/bots/{botID}/customer-sdk: ứng dụng được phép và trạng thái bật.
  • POST /api/bots/{botID}/customer-sdk/rotate-secret: trả bí mật mới; bí mật cũ còn hoạt động thêm một ngày.
  • DELETE /api/bots/{botID}/customer-sdk/installations/{installationID}: thu hồi một thiết bị.

Đường dẫn phía ứng dụng khách /sdk/v1/* không thuộc API này. Chúng dùng token bản cài và phiên bản định danh, không chấp nhận PAT; ngược lại /api/* không chấp nhận token bản cài. Tài liệu OpenAPI riêng công khai ở GET /sdk/openapi.yaml.

Gửi hàng loạt

Nhóm này chỉ có một scope là broadcasts:write, không có broadcasts:read. Vì vậy ngay cả việc đọc danh sách, báo cáo và người nhận theo trang cũng cần broadcasts:write. Không thể cấp token chỉ đọc gửi hàng loạt. Mọi endpoint còn kiểm tra quyền Phản ứng của bot.

Gửi hàng loạt thế hệ hai dùng nội dung, đối tượng nhận và kênh:

  • GET /api/bots/{botID}/broadcasts: danh sách; ?archived=true thêm mục lưu trữ.
  • POST /api/bots/{botID}/broadcasts: tạo bản nháp.
  • PATCH /api/bots/{botID}/broadcasts/{broadcastID}: sửa bản nháp.
  • POST /api/bots/{botID}/broadcasts/{broadcastID}/preflight: kiểm tra người nhận, không gửi gì nhưng vẫn ghi nhật ký vì là POST.
  • POST /api/bots/{botID}/broadcasts/{broadcastID}/schedule: khởi chạy.
  • POST /api/bots/{botID}/broadcasts/{broadcastID}/test-send: gửi thử cho một liên hệ đã xác minh.
  • POST /api/bots/{botID}/broadcasts/{broadcastID}/archive: lưu trữ.
  • GET /api/bots/{botID}/broadcasts/{broadcastID}/report: báo cáo theo kênh.
  • GET /api/bots/{botID}/broadcasts/{broadcastID}/recipients: người nhận, dùng limit và cursor.

Cách cũ, gửi dựa trên phản ứng, vẫn dùng cùng đường dẫn gốc. Khởi chạy qua POST /api/bots/{botID}/reactions/{reactionID}/broadcast với {"paid": false, "labels": ["vip"]}. Đây là nơi duy nhất lọc đợt gửi theo nhãn. Hai nhóm dùng chung GET /api/bots/{botID}/broadcasts/{broadcastID} và POST /api/bots/{botID}/broadcasts/{broadcastID}/pause|resume|cancel.

Máy chủ tìm đợt gửi thế hệ hai trước, rồi mới tìm bản cũ; nội dung yêu cầu và câu trả lời tùy loại ID. Đợt mới cần {"expected_revision": N} và trả toàn bộ đối tượng; đợt cũ bỏ qua body, trả {"status": "pausing"}, {"status": "resuming"} hoặc {"status": "canceled"}. Body nghiêm ngặt: trường lạ gây 400. Khi sửa đợt mới, gửi expected_revision đã đọc; 409 nghĩa là tải lại rồi thử tiếp. schedule còn cần "confirm": true, nếu thiếu trả 400.

Các mã lỗi đáng chú ý:

  • 402: gói của chủ sở hữu không có tính năng gửi hàng loạt.
  • 403: chưa bật gửi hàng loạt trả phí cho bot này.
  • 409: phiên bản đã cũ hoặc chưa sẵn sàng chạy (nội dung chưa xuất bản, phân khúc chưa tính lại, thử nghiệm chưa bắt đầu, không có người nhận).
  • 422: thiếu nội dung hoặc nội dung không hợp lệ cho một kênh.
  • 429: gửi thử quá thường xuyên.

Trong MCP, cùng scope này dùng cho start_broadcast, get_broadcast, pause_broadcast, resume_broadcast, cancel_broadcast, list_content_broadcasts và get_content_broadcast_report. Hai công cụ cuối và get_broadcast chỉ đọc nhưng vẫn cần broadcasts:write. Tạo/sửa bản nháp, kiểm tra người nhận, chạy, gửi thử và lưu trữ đợt thế hệ hai chỉ có trong REST; công cụ pause/resume/cancel của MCP chỉ làm việc với đợt cũ theo phản ứng. Xem Gửi hàng loạt.

Truy cập trên di động

Ứng dụng di động của nền tảng dùng access token và refresh token riêng, có bảng tổng quan nhiều bot và cùng sử dụng backend.

Tài liệu API

Tài liệu API tương tác liệt kê endpoint công khai dùng được với PAT, tham số, schema, scope và ví dụ curl, JavaScript, Python. Bạn có thể thử yêu cầu ngay trên trang bằng token của mình.

Phễu và thử nghiệm

Định nghĩa và báo cáo phễu đã lưu dùng analytics:read và analytics:write; lưu một cohort thành phân khúc còn cần segments:write. Định nghĩa, vòng đời, báo cáo và cohort thử nghiệm dùng experiments:read và experiments:write. Mọi endpoint còn kiểm tra quyền Phân tích của bot. Nhật ký kiểm toán ghi mọi POST, PUT, PATCH, DELETE đã xác thực của chủ sở hữu, kể cả yêu cầu báo cáo, query hoặc cohort chỉ đọc về mặt ý nghĩa nhưng dùng POST. GET không tạo sự kiện kiểm toán.

Với báo cáo, luôn gửi khoảng thời gian hữu hạn RFC3339 theo UTC. Phễu và thử nghiệm giới hạn 366 ngày. Doanh thu thử nghiệm gồm số nguyên minor và mã tiền ISO 4217 currency; đừng tự gộp nhiều tiền tệ ở client.

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

Gửi lại cursor next do máy chủ trả mà không sửa. Cursor hoặc body sai trả 400; tài nguyên bot không truy cập được hoặc phiên bản thử nghiệm được yêu cầu rõ nhưng không có trả 404. Phiên bản chỉnh sửa cũ hoặc xung đột khi chọn người thắng trả 409. Xem body/schema trong Tài liệu API, Phễu và Thử nghiệm.

Bảo mật

  • Token chỉ hiển thị một lần; lưu như bí mật.
  • Bí mật bot và thông tin xác thực được lưu dưới dạng mã hóa.
  • Nhật ký kiểm toán ghi POST, PUT, PATCH và DELETE đã xác thực, không ghi lượt đọc GET.

Customer AI, phân tích kịch bản, playbook và Meta

Các tên API sau giữ tiếng Anh; bên cạnh là mục đích:

  • Managed AI: POST /api/v1/ai/responses (managed_ai:invoke) gọi AI; GET /api/v1/ai/usage (managed_ai:usage:read) đọc mức dùng. Profile fast, balanced, quality; provider auto, openai, anthropic, deepseek. Lời gọi cần Idempotency-Key. Khóa nhà cung cấp của bạn lỗi sẽ không tự chuyển sang Managed AI trả phí.
  • Copilot: tạo đề xuất sửa phản ứng ở /api/reactions/{rootID}/copilot/proposals. Đọc, xác thực, chạy thử, áp dụng hoặc từ chối qua /api/copilot/proposals/{proposalID}. Áp dụng tạo bản nháp, không tự xuất bản.
  • Flow Intelligence: xem hành trình qua phản ứng, ví dụ thực thi và quy tắc phân tích; cấu hình và tính lại trong khoảng giới hạn tại /api/bots/{botID}/flow-intelligence/*.
  • Explainable Replay: đọc và phát lại nhật ký thực thi, tạo ví dụ kiểm tra đã loại dữ liệu nhạy cảm và chạy kiểm tra hồi quy. Tác nhân không được mở tài liệu được bảo vệ.
  • Vertical Playbooks: danh mục /api/playbooks/catalog, tiếp tục cấu hình dở, kiểm tra, cài đặt, nâng cấp và chỉ số kết quả (KPI).
  • Outcome onboarding: cấu hình ban đầu theo mục tiêu qua POST|PATCH /api/onboarding/session và POST /api/onboarding/session/complete.
  • Messenger và Instagram: /api/meta/connections trả URL để cấp quyền Meta trong trình duyệt; sau đó kiểm tra, chọn và gắn trang, tài khoản trong tài khoản của bạn. Không trả token bí mật.

Chỉ siêu quản trị viên mới quản lý khóa nhà cung cấp, định tuyến, giá và đối soát chi phí; API/MCP của người dùng không có quyền đó. Copilot, Flow Intelligence, Explainable Replay và Vertical Playbooks phải được bật cho tài khoản của bạn; nếu chưa, yêu cầu bị từ chối trên cả REST lẫn MCP.

Bước tiếp theo