API dành cho Đại lý #

Với tư cách là một đại lý, bạn có thể sử dụng cùng REST API mà khách hàng của bạn sử dụng, nhưng hãy hướng các yêu cầu riêng lẻ đến một trong các tài khoản phụ được quản lý của bạn thay vì tài khoản của chính bạn. Điều này cho phép bạn xây dựng các công cụ giúp khách hàng bắt đầu sử dụng từ đầu đến cuối — tạo chiến dịch, đào tạo AI của họ trên cơ sở kiến thức, nhập danh bạ, kết nối các kênh nhắn tin và mua số điện thoại — tất cả mà không cần phải đăng nhập thủ công vào từng tài khoản phụ.

Trang này chỉ bao gồm các hành vi dành riêng cho đại lý: cách thực hiện thay mặt cho một tài khoản phụ với tham số sub_account_id. Để biết các kiến thức cơ bản (tạo khóa, xác thực, URL cơ sở, định dạng lỗi, giới hạn tốc độ), hãy bắt đầu với hướng dẫn Truy cập API. Mọi thông tin ở đó cũng áp dụng tại đây — bạn xác thực bằng khóa API của tài khoản đại lý của bạn.

Cách thức hoạt động của “thực hiện thay mặt” #

Theo mặc định, mọi yêu cầu API đều thực hiện trên tài khoản sở hữu khóa API — tài khoản đại lý của bạn. Để thực hiện trên tài khoản khách hàng được quản lý thay vào đó, hãy thêm tham số tùy chọn sub_account_id vào yêu cầu, được đặt thành id tài khoản của khách hàng đó.

• Bỏ qua sub_account_id → yêu cầu thực hiện trên tài khoản đại lý của chính bạn.
• Bao gồm sub_account_id → yêu cầu thực hiện trên tài khoản phụ đó, nhưng chỉ sau khi nền tảng xác nhận tài khoản phụ đó thực sự thuộc về bạn.

Bạn luôn xác thực bằng khóa API của tài khoản đại lý của bạn. Bạn không bao giờ cần khóa riêng của tài khoản phụ và bạn không bao giờ phải xử lý thông tin đăng nhập của tài khoản phụ.

Vị trí đặt tham số #

• Các endpoint GET / DELETE → truyền nó dưới dạng tham số truy vấn: ?sub_account_id=THE_SUB_ACCOUNT_ID (cùng với apiKey của bạn, nếu bạn xác thực bằng truy vấn).
• Các endpoint POST / PUT / PATCH → bao gồm nó trong phần thân yêu cầu JSON dưới dạng "sub_account_id": "THE_SUB_ACCOUNT_ID".
• Trợ lý AI → không cần cấu hình gì cả. Máy chủ MCP mang cùng một thiết lập trên các công cụ đọc của nó, vì vậy một kết nối với khóa đại lý của bạn có thể báo cáo về mọi khách hàng: chỉ cần nêu tên khách hàng trong yêu cầu của bạn (“Bella’s Bistro có bao nhiêu liên hệ?”). Các hành động ghi cũng khả dụng: mọi endpoint chấp nhận sub_account_id đều được hiển thị dưới dạng một công cụ, vì vậy bạn có thể tạo, thay đổi và gửi thay mặt khách hàng từ cùng một kết nối.

Tìm id của tài khoản phụ #

sub_account_id là id duy nhất của tài khoản khách hàng. Bạn có thể lấy danh sách các tài khoản phụ và id của chúng từ các điểm cuối API SubAccounts (xem hướng dẫn Sub-Accounts) hoặc từ trang Sub Accounts trong thanh bên.

Quyền sở hữu luôn được xác minh #

Khi bạn truyền một sub_account_id, nền tảng sẽ kiểm tra xem tài khoản đó có phải là tài khoản phụ thực sự và có thuộc về đại lý của bạn hay không. Chỉ khi đó yêu cầu mới được thực hiện.

Nếu id không xác định, không phải là tài khoản phụ hoặc thuộc về một đại lý khác, yêu cầu sẽ thất bại với phản hồi 404:

{
  "success": false,
  "error_code": 404,
  "error": "Sub-account not found."
}

Tại sao lại là 404 mà không phải 403? Phản hồi “forbidden” (bị cấm) sẽ cho người ngoài biết rằng id đó tồn tại nhưng không thuộc về họ. Việc trả về cùng một 404 cho cả trường hợp “không tồn tại” và “không thuộc về bạn” có nghĩa là endpoint không thể bị lợi dụng để khám phá xem id tài khoản nào thuộc về các đại lý khác. Hãy coi 404 ở đây là “đây không phải là tài khoản phụ mà bạn quản lý.”

Nơi hỗ trợ sub_account_id #

sub_account_id được chấp nhận trên hầu hết mọi điểm cuối tài nguyên — bất kỳ lệnh gọi nào tạo, đọc, cập nhật hoặc xóa dữ liệu của chính tài khoản đó. Trên thực tế, bạn có thể cung cấp và chạy toàn bộ thiết lập của một tài khoản phụ bằng khóa đại lý của mình:

• Thiết lập AI — chiến dịch, tác nhân, câu hỏi thường gặp (FAQ), nguồn cơ sở kiến thức (thu thập dữ liệu trang web và tải lên tài liệu), nhóm cơ sở kiến thức, chương trình phát sóng, hàm tùy chỉnh, máy chủ MCP
• Danh bạ & CRM — danh bạ (bao gồm cả nhập danh bạ), danh sách, thẻ, tác vụ, giao dịch, cuộc hẹn, sự kiện
• Kênh & số điện thoại — kết nối WhatsApp / WhatsApp Web / Telegram / Instagram & Messenger / LINE, tìm kiếm / mua / quản lý số điện thoại, mẫu WhatsApp, định tuyến kênh
• Nhắn tin & nội dung — gửi tin nhắn, phiên trò chuyện, xuất dữ liệu trò chuyện, tóm tắt hàng ngày
• Cài đặt & tích hợp — webhook, cấu hình tiện ích trò chuyện, cấu hình nhãn trắng (white-label), SMS BYOK và các cài đặt tài khoản khác, phân tích

Đối với mỗi tham số này, tham số đó là tùy chọn — hãy bỏ qua nó và lệnh gọi sẽ thực hiện trên tài khoản đại lý của chính bạn, vì vậy một tích hợp có thể phục vụ cả hai. Tín dụng và mức sử dụng luôn được tính từ tài khoản mà bạn nhắm mục tiêu: các khoản phí cho chiến dịch, tin nhắn, thẻ và số điện thoại của tài khoản phụ sẽ được tính vào số dư của tài khoản phụ đó.

Trường hợp KHÔNG áp dụng #

Một vài endpoint là cấp đại lý hoặc tự tham chiếu và bỏ qua sub_account_id:

• Quản lý chính các tài khoản phụ — các endpoint SubAccounts (tạo / liệt kê / cập nhật tài khoản phụ) và endpoint giới hạn chi tiêu BYOK đã đặt tên cho tài khoản phụ trong đường dẫn URL của riêng chúng. Các endpoint về giá và chính sách và endpoint giám sát trò chuyện cũng tuân theo mô hình tương tự.
• Sao chép một Agent giữa các tài khoản — POST /v1/subaccounts/agents/copy tự đặt tên cho cả hai tài khoản, lấy đích đến là targetUserId. Xem ví dụ thực tế bên dưới. (POST /v1/subaccounts/campaigns/copy cũ hơn hoạt động theo cách tương tự nhưng đã bị loại bỏ cùng với phần còn lại của Campaigns API.)
• Điều chỉnh tín dụng và hai bản tổng hợp toàn đại lý — POST /v1/subaccounts/credits xác định tài khoản phụ bằng email thay thế; GET /v1/subaccounts/credit-usage và GET /v1/subaccounts/campaign-status báo cáo về mọi tài khoản phụ cùng một lúc, vì vậy không có tài khoản đơn lẻ nào để nhắm mục tiêu.
• Tài khoản riêng của đại lý — Quản lý khóa API, báo cáo sử dụng của đại lý, quản lý nhóm và các cấp giá của bạn luôn hoạt động trên tài khoản đại lý của bạn.
• Webhook tin nhắn đến — các endpoint mà hệ thống bên ngoài gửi vào được gắn với tài khoản có thông tin xác thực đã định cấu hình chúng, vì vậy không có gì để chuyển hướng.

Danh sách các tham số mà mỗi điểm cuối chấp nhận luôn được cập nhật và có thể đọc được bằng máy nằm trong tài liệu tham khảo API trên bảng điều khiển của bạn (Settings → Integrations → API Key) và thông số kỹ thuật OpenAPI tại GET /v1/docs/openapi.yaml. Chúng tôi thường xuyên cập nhật API — hãy coi đó là nguồn thông tin chính xác nhất.

Ví dụ thực tế: kết nối Instagram & Messenger cho một tài khoản phụ #

Việc kết nối Instagram & Messenger là một quy trình dựa trên trình duyệt. Bạn bắt đầu bằng API, cung cấp URL xác nhận được trả về cho khách hàng (hoặc mở nó cho họ), đợi họ ủy quyền trong trình duyệt của họ, sau đó chọn trang để kết nối — tất cả đều trong khi nhắm mục tiêu vào tài khoản phụ của họ bằng sub_account_id.

Bước 1 — Bắt đầu kết nối #

Gọi endpoint kết nối với sub_account_id của khách hàng trong phần body. Không có thông tin xác thực nào được gửi ở đây; nền tảng sẽ trả về một URL xác nhận mà khách hàng phải mở trong trình duyệt, cùng với một mã token tương quan dùng một lần.

cURL

curl -X POST "https://api.dmchamp.com/v1/channels/meta/connect?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sub_account_id": "abc123def456"
  }'

JavaScript

const res = await fetch("https://api.dmchamp.com/v1/channels/meta/connect", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    sub_account_id: "abc123def456",
  }),
});

const data = await res.json();
// data.oauth_url -> open this in the client's browser

Python

import requests

res = requests.post(
    "https://api.dmchamp.com/v1/channels/meta/connect",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "sub_account_id": "abc123def456",
    },
)

data = res.json()
# data["oauth_url"] -> open this in the client's browser

Phản hồi:

{
  "success": true,
  "oauth_url": "https://www.facebook.com/v21.0/dialog/oauth?client_id=...&state=...",
  "state_token": "8sFq2yV0kQ7m4n1pZr3tWb6cXe9hJl2aD5gK7uN0oI",
  "expires_at": "2026-06-10T12:30:00.000Z"
}

Hướng khách hàng đến oauth_url trong trình duyệt để ủy quyền. state_token sẽ tương quan nỗ lực này và là một bí mật có thời hạn ngắn — đừng ghi lại nó. Nỗ lực này sẽ hết hạn tại expires_at; nếu quá thời hạn, hãy bắt đầu lại.

Bước 2 — Thăm dò cho đến khi các trang được tải #

Sau khi khách hàng ủy quyền, hãy thăm dò điểm cuối trạng thái (với cùng sub_account_id, lần này là tham số truy vấn) cho đến khi các trang có thể kết nối xuất hiện.

cURL

curl "https://api.dmchamp.com/v1/channels/meta/status?apiKey=YOUR_API_KEY&sub_account_id=abc123def456"

JavaScript

const res = await fetch(
  "https://api.dmchamp.com/v1/channels/meta/status?sub_account_id=abc123def456",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);

const data = await res.json();
// Wait until data.status === "pages_loaded", then read data.pages

Python

import requests

res = requests.get(
    "https://api.dmchamp.com/v1/channels/meta/status",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"sub_account_id": "abc123def456"},
)

data = res.json()
# Wait until data["status"] == "pages_loaded", then read data["pages"]

Phản hồi:

{
  "success": true,
  "status": "pages_loaded",
  "pages": [
    {
      "id": "1098765432101234",
      "name": "Acme Studio",
      "category": "Hair Salon",
      "instagram_business_account": {
        "id": "17841400000000000",
        "username": "acme.studio"
      }
    }
  ],
  "selected_page": null
}

Trường status chuyển qua pending → token_received → pages_loaded → connected. Hãy đợi pages_loaded trước khi chọn trang. Hai trạng thái lỗi cuối cùng cũng có thể xuất hiện thay vì tiến trình tiếp tục: failed và expired (khách hàng từ chối cấp quyền hoặc cửa sổ ~30 phút của mã thông báo trạng thái đã hết hạn) — một trường reason sẽ được bao gồm khi một trong hai trường hợp này xảy ra. Hãy dừng việc thăm dò và bắt đầu lại từ Bước 1 nếu bạn thấy một trong các lỗi này; đừng đợi pending mãi mãi. Mã thông báo truy cập trang không bao giờ được trả về.

Bước 3 — Chọn trang để kết nối #

Chọn một trong các id trang từ Bước 2 và chọn nó. Việc chọn một trang sẽ kết nối cả Instagram và Messenger cho trang đó. Hãy đưa sub_account_id vào phần thân yêu cầu một lần nữa.

cURL

curl -X POST "https://api.dmchamp.com/v1/channels/meta/select-page?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "page_id": "1098765432101234",
    "sub_account_id": "abc123def456"
  }'

JavaScript

const res = await fetch("https://api.dmchamp.com/v1/channels/meta/select-page", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    page_id: "1098765432101234",
    sub_account_id: "abc123def456",
  }),
});

const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.dmchamp.com/v1/channels/meta/select-page",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "page_id": "1098765432101234",
        "sub_account_id": "abc123def456",
    },
)

data = res.json()

Phản hồi:

{
  "success": true,
  "page_id": "1098765432101234",
  "instagram_business_account_id": "17841400000000000"
}

Vậy là xong — Instagram và Messenger hiện đã được kết nối trên tài khoản phụ của khách hàng. Bạn chỉ cần cung cấp page_id; thông tin xác thực cơ bản được giải quyết trên máy chủ và không bao giờ được chuyển qua tích hợp của bạn.

Ví dụ thực tế: mua một số điện thoại cho tài khoản phụ #

Việc mua số điện thoại hoạt động theo cách tương tự: tìm kiếm với sub_account_id trong truy vấn, sau đó mua với nó trong phần thân yêu cầu. Tín dụng sẽ được trừ vào số dư của tài khoản phụ và số điện thoại sẽ được cung cấp cho tài khoản phụ đó.

Tìm kiếm (cURL):

curl "https://api.dmchamp.com/v1/phone-numbers/available?apiKey=YOUR_API_KEY&country_code=US&sub_account_id=abc123def456"

Mua hàng (JavaScript):

const res = await fetch("https://api.dmchamp.com/v1/phone-numbers", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    phone_number: "+14155551234",
    country_code: "US",
    display_name: "Support line",
    sub_account_id: "abc123def456",
  }),
});

const data = await res.json();

Mua hàng (Python):

import requests

res = requests.post(
    "https://api.dmchamp.com/v1/phone-numbers",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "phone_number": "+14155551234",
        "country_code": "US",
        "display_name": "Support line",
        "sub_account_id": "abc123def456",
    },
)

data = res.json()

Phản hồi:

{
  "success": true,
  "phone_number": "+14155551234",
  "channel": "whatsapp",
  "whatsapp_status": "PURCHASED",
  "outgoing_status": "PURCHASED",
  "status": "PURCHASED",
  "purchase_credits": 11.5,
  "monthly_credits": 11.5
}

Số điện thoại được cung cấp ở trạng thái PURCHASED và quá trình đăng ký người gửi WhatsApp tiếp tục ở chế độ nền. Hãy thăm dò GET /v1/phone-numbers/{phoneNumber}/status?sub_account_id=abc123def456 cho đến khi trạng thái đạt ONLINE trước khi gửi.

Ví dụ thực tế: chuyển một Agent mẫu vào mọi khách hàng mới #

Mô hình đại lý thông thường là giữ một Agent chính trên tài khoản đại lý của bạn, được tinh chỉnh theo cách bạn muốn mọi khách hàng bắt đầu, và đóng dấu một bản sao của nó vào mỗi tài khoản phụ mới tại thời điểm cung cấp. Đó là ba lệnh gọi và không cần lặp lại sau đó: bản sao giữ nguyên các cài đặt của nó cho đến khi bạn thay đổi chúng.

Bước 1 — Sao chép Agent vào #

POST /v1/subaccounts/agents/copy

curl -X POST "https://api.dmchamp.com/v1/subaccounts/agents/copy?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "YOUR_TEMPLATE_AGENT_ID",
    "targetUserId": "abc123def456",
    "newName": "Inbound Instagram Leads",
    "copyFaqs": true
  }'

Phản hồi mang theo id của Agent mới tại data.agent_id. Các câu hỏi thường gặp, cơ sở kiến thức và thư viện phương tiện sẽ đi kèm; các mẫu WhatsApp, bài đăng xã hội được kết nối và danh bạ của tài khoản nguồn sẽ cố tình không được sao chép. Danh sách trường đầy đủ có trong AI Agents API.

Lưu ý điểm cuối này lấy targetUserId thay vì sub_account_id — nó tự đặt tên cho cả hai tài khoản. Hai lệnh gọi bên dưới sử dụng tham số sub_account_id thông thường.

Bước 2 — Bật nó lên #

Bản sao luôn ở trạng thái tạm dừng khi đến nơi, vì vậy nó không thể nhắn tin cho bất kỳ ai cho đến khi bạn cho phép. Đây cũng là thời điểm để ghim cấp độ AI mà bạn muốn khách hàng sử dụng; nó sẽ ở đó, vì vậy không cần phải áp dụng lại theo lịch trình.

curl -X PATCH "https://api.dmchamp.com/v1/agents/NEW_AGENT_ID/active?apiKey=YOUR_API_KEY&sub_account_id=abc123def456" \
  -H "Content-Type: application/json" \
  -d '{ "active": true }'

curl -X PUT "https://api.dmchamp.com/v1/agents/NEW_AGENT_ID?apiKey=YOUR_API_KEY&sub_account_id=abc123def456" \
  -H "Content-Type: application/json" \
  -d '{ "anthropic_model": "max" }'

Để ngăn khách hàng thay đổi cấp độ sau đó, hãy khóa các cấp độ được phép trên tài khoản phụ thay vì gửi lại giá trị.

Bước 3 — Trỏ các kênh của khách hàng vào chiến dịch #

Bản sao cũng đến mà không có định tuyến, vì vậy không có gì tiếp cận được nó cho đến khi bạn biến nó thành người trả lời trên các kênh mà khách hàng đã kết nối. Một lệnh gọi cho mỗi kênh:

curl -X PUT "https://api.dmchamp.com/v1/entry-points/channel-defaults?apiKey=YOUR_API_KEY&sub_account_id=abc123def456" \
  -H "Content-Type: application/json" \
  -d '{ "channel": "instagram", "agent_id": "NEW_AGENT_ID" }'

Từ đây, tin nhắn lần đầu từ một liên hệ không xác định trên kênh đó sẽ được Agent đã sao chép tự động nhận. Xem Trỏ một kênh vào một Agent để biết các kênh khác và định tuyến theo số.

Đặt múi giờ của khách hàng khi bạn tạo tài khoản phụ. Truyền time_zone_id trên POST /v1/subaccounts. Giờ hoạt động của chiến dịch được đánh giá theo múi giờ riêng của tài khoản phụ, vì vậy khách hàng được tạo mà không có múi giờ sẽ có lịch trình được đọc theo UTC — điều này làm thay đổi âm thầm thời điểm trợ lý được phép trả lời.

Bỏ qua trình hướng dẫn thiết lập cho khách hàng mà bạn tự cấu hình #

POST /v1/subaccounts

Theo mặc định, lần đầu tiên chủ sở hữu tài khoản phụ mới đăng nhập, họ sẽ được hướng dẫn qua Trình hướng dẫn thiết lập. Đối với các khách hàng sử dụng dịch vụ trọn gói — nơi bạn xây dựng chiến dịch và kết nối các kênh trước khi khách hàng đăng nhập — hãy truyền guided_onboarding: false khi bạn tạo tài khoản. Họ sẽ được đưa đến bảng điều khiển thay vì trình hướng dẫn, và mục Trình hướng dẫn thiết lập sẽ bị ẩn khỏi thanh bên của họ.

curl -X POST "https://api.dmchamp.com/v1/subaccounts" \
  -H "X-API-Key: YOUR_AGENCY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "client@example.com",
    "first_name": "Alex",
    "last_name": "Client",
    "business_name": "Client Co",
    "guided_onboarding": false,
    "usage_limits": { "monthly_credits": 500 }
  }'

Bỏ qua trường này (hoặc gửi true) và trình hướng dẫn sẽ hoạt động chính xác như trước đây, vì vậy các tích hợp hiện có không cần thay đổi. Để cung cấp lại trình hướng dẫn cho khách hàng sau này, hãy hiển thị lại mục guided_onboarding với PUT /v1/subaccounts/{subAccountUid}/menu-visibility (bên dưới) — khả năng hiển thị menu kiểm soát xem trình hướng dẫn có thể truy cập được hay không, guided_onboarding chỉ kiểm soát việc chuyển hướng đăng nhập lần đầu.

Tắt Tác vụ, Tóm tắt hàng ngày hoặc Thư viện phương tiện cho khách hàng #

POST /v1/subaccounts

Ba tính năng này được bật cho mọi khách hàng mới trừ khi bạn chỉ định khác, và chúng hoạt động khác với mọi tính năng khác trong hướng dẫn này: chúng là tùy chọn từ chối (opt-out), không phải tùy chọn tham gia (opt-in). Việc loại bỏ chúng khỏi features là chưa đủ, vì danh sách features của một tích hợp cũ hơn đơn giản là không bao giờ đề cập đến chúng — chúng tôi không thể phân biệt được “đại lý đã tắt tính năng này” với “danh sách này được viết trước khi tùy chọn tồn tại”.

Vì vậy, hãy nêu rõ điều đó với feature_settings:

curl -X POST "https://api.dmchamp.com/v1/subaccounts" \
  -H "X-API-Key: YOUR_AGENCY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "client@example.com",
    "first_name": "Alex",
    "last_name": "Client",
    "business_name": "Client Co",
    "feature_settings": {
      "tasks": false,
      "daily_summaries": false,
      "ai_media_library": true
    }
  }'

Mọi khóa đều là tùy chọn; bất cứ thứ gì bạn bỏ qua sẽ vẫn được bật. Với tasks: false, AI sẽ ngừng tạo tác vụ cho khách hàng đó và không có email “Tác vụ mới được tạo” nào được gửi đi; với daily_summaries: false, bản tóm tắt hàng đêm sẽ không bao giờ được tạo hoặc gửi qua email.

feature_settings là thứ duy nhất tắt ba tính năng này khi tạo. Việc loại bỏ chúng khỏi features không có tác dụng gì, bất kể danh sách còn lại của bạn trông như thế nào — điều đó là cố ý, để một tích hợp cũ hơn không bị mất cả ba tính năng này một cách âm thầm.

Để thay đổi bất kỳ điều nào trong số này sau đó, hãy gửi toàn bộ danh sách features tới PUT /v1/subaccounts/{subAccountUid}/features — ở đó, sự hiện diện trong danh sách sẽ bật một tính năng và sự vắng mặt sẽ tắt nó đi.

Tự động đăng nhập cho khách hàng vào tài khoản phụ của họ (SSO) #

POST /v1/subaccounts/{subAccountUid}/sso-link

Chỉ cần một lệnh gọi với khóa API đại lý của bạn, bạn sẽ nhận được một URL sẵn sàng để mở, giúp đăng nhập trực tiếp khách hàng vào tài khoản phụ của họ — không cần màn hình đăng nhập, không cần bước nhập mật khẩu, không cần xây dựng thêm bất cứ thứ gì. Bạn có thể mở URL này trong tab mới, chuyển hướng hoặc iframe bên trong sản phẩm của chính bạn.

cURL

curl -X POST "https://api.dmchamp.com/v1/subaccounts/SUB_ACCOUNT_UID/sso-link" \
  -H "X-API-Key: YOUR_AGENCY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "redirect": "/chats" }'

Phản hồi

{
  "success": true,
  "url": "https://app.yourdomain.com/auth?redirect=%2Fchats#token=eyJhbGciOi…",
  "deep_link_url": "https://app.yourdomain.com/chats",
  "expires_at": "2026-07-22T15:04:05.000Z",
  "sub_account_uid": "SUB_ACCOUNT_UID"
}

Cách sử dụng hiệu quả:

• Một bước. Việc mở url sẽ đăng nhập cho khách hàng và đưa họ trực tiếp đến trang redirect của bảng điều khiển — không cần màn hình đăng nhập, không cần trang trung gian. deep_link_url chỉ định cùng một đích đến, dành cho các nhà tích hợp muốn điều hướng khung hình một cách rõ ràng sau khi đăng nhập; khi phiên làm việc đã tồn tại, bất kỳ đường dẫn bảng điều khiển nào cũng hoạt động trong ngữ cảnh trình duyệt đó.
• Tạo theo yêu cầu, mở ngay lập tức. Liên kết chứa thông tin xác thực đăng nhập và hết hạn sau khoảng một giờ. Hãy yêu cầu nó từ phía máy chủ ngay tại thời điểm khách hàng nhấp vào, và không bao giờ lưu trữ hoặc gửi nó qua email.
• Mã thông báo đăng nhập được truyền trong phần phân đoạn URL (#…), phần mà trình duyệt không bao giờ gửi đến máy chủ, và nó sẽ bị xóa khỏi thanh địa chỉ ngay khi được sử dụng.
• Chỉ các tài khoản phụ của riêng bạn. Điểm cuối sẽ từ chối bất kỳ tài khoản nào mà đại lý của bạn không sở hữu.
• Một liên kết hết hạn sẽ hiển thị lỗi rõ ràng kèm theo đường dẫn thử lại — hãy tạo một liên kết mới.

Ẩn các mục điều hướng trên tài khoản phụ #

PUT /v1/subaccounts/{subAccountUid}/menu-visibility

Kiểm soát những mục nào trên thanh bên và cài đặt mà tài khoản phụ có thể nhìn thấy — hữu ích khi bạn nhúng bảng điều khiển và chỉ muốn hiển thị những phần mà sản phẩm của bạn chưa bao phủ. Bất kỳ mục nào không được liệt kê sẽ vẫn hiển thị; hãy gửi null dưới dạng toàn bộ giá trị menuVisibility để đặt lại mọi thứ về trạng thái hiển thị. Việc ẩn một mục sẽ ẩn luôn mục menu đó — hãy kết hợp với các tính năng bạn cấp cho tài khoản phụ để kiểm soát quyền truy cập chặt chẽ.

cURL

curl -X PUT "https://api.dmchamp.com/v1/subaccounts/SUB_ACCOUNT_UID/menu-visibility" \
  -H "X-API-Key: YOUR_AGENCY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "menuVisibility": {
      "side_nav": { "Dashboard": false, "Campaigns": false, "Automations": false },
      "settings_nav": { "team": false }
    }
  }'

Phản hồi

{
  "success": true,
  "data": {
    "subAccountUid": "SUB_ACCOUNT_UID",
    "menuVisibility": {
      "side_nav": { "Dashboard": false, "Campaigns": false, "Automations": false },
      "settings_nav": { "team": false }
    }
  }
}

side_nav chấp nhận 13 khóa này, khớp với tên các mục trên thanh bên: Dashboard, DailySummaries, Chats, Contacts, Deals, Tasks, Automations, Campaigns, Appointments, Settings, Help, CreditsCounter (số dư tín dụng hiển thị trên thanh bên) và guided_onboarding (Trình hướng dẫn thiết lập). Ba khóa khác — AiInsights, Sub Accounts và Agency Reselling — được chấp nhận nhưng không có tác dụng gì: chúng chỉ áp dụng cho bảng điều khiển cổ điển đã ngừng hoạt động, vì vậy việc thiết lập chúng không ảnh hưởng đến các tài khoản phụ của bạn. Các khóa bị thiếu nghĩa là hiển thị; khi bạn tự đăng nhập vào tài khoản phụ, các mục bị ẩn sẽ tạm thời được hiển thị để bạn luôn có thể thay đổi lại mọi thứ.

Việc ẩn một trang khỏi menu không bao giờ cấp quyền truy cập vào trang đó. Automations cần tính năng automations được cấp trên tài khoản phụ — đặt khóa thành true mà không có tính năng đó thì trang vẫn sẽ không xuất hiện. Tasks và DailySummaries hoạt động theo cách ngược lại: chúng được bật cho mọi khách hàng trừ khi bạn tắt chúng đi (xem Tắt Tác vụ, Tóm tắt hàng ngày hoặc Thư viện phương tiện cho khách hàng).

Chọn loại kênh mà khách hàng có thể kết nối #

PUT /v1/subaccounts/{subAccountUid}/features

Các công tắc Loại kênh (Channel Types) mà bạn thấy trên một gói dịch vụ là các ID tính năng thông thường, vì vậy bạn có thể thiết lập chúng cho từng khách hàng từ API thay vì từ bảng điều khiển. Đây là một trong những endpoint đặt tên cho tài khoản phụ trong chính URL của nó, vì vậy nó không yêu cầu sub_account_id.

curl -X PUT "https://api.dmchamp.com/v1/subaccounts/SUB_ACCOUNT_UID/features" \
  -H "X-API-Key: YOUR_AGENCY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "features": [
      "channels_3",
      "channel_chat_widget",
      "channel_whatsapp_web",
      "channel_instagram",
      "image_understanding",
      "contact_tagging",
      "incoming_campaigns",
      "webhooks"
    ]
  }'

Ba điều cần lưu ý:

• Lệnh gọi này thay thế toàn bộ danh sách tính năng. Hãy gửi mọi tính năng mà khách hàng cần giữ lại, không chỉ những tính năng bạn đang thay đổi. Các ID tương tự cũng hoạt động như features trên POST /v1/subaccounts khi bạn tạo tài khoản.
• Loại kênh và số lượng kênh là các cổng kiểm soát riêng biệt và cả hai đều được áp dụng. channels_1 / channels_3 / channels_unlimited kiểm soát số lượng kết nối; các ID channel_* kiểm soát loại kênh nào. Ví dụ trên có nghĩa là “tối đa 3 kết nối và chỉ bao gồm Tiện ích trò chuyện, WhatsApp Web hoặc Instagram”.
• Việc không gửi bất kỳ ID channel_* nào đồng nghĩa với việc không có hạn chế về kênh. Đó là hành vi ban đầu, đó là lý do tại sao các khách hàng hiện tại không bị ảnh hưởng khi tính năng này được phát hành. Hãy gửi một hoặc nhiều ID và mọi thứ khác sẽ hiển thị là bị khóa trên trang Kênh của khách hàng với ghi chú nâng cấp thay vì nút Kết nối. Các kênh mà khách hàng đã kết nối vẫn tiếp tục hoạt động.

Việc thiết lập danh sách kênh trên một gói dịch vụ, để mọi khách hàng mua gói đó đều được kế thừa, được thực hiện trong bảng điều khiển trong phần cài đặt gói đại lý của bạn. Endpoint này thiết lập danh sách đó cho một tài khoản phụ cụ thể.

Đặt giới hạn số lượng thành viên nhóm chính xác cho khách hàng #

PUT /v1/subaccounts/{subAccountUid}/limits

Các tính năng team_seats_* chỉ cung cấp các bước thang đo được thiết lập sẵn (3 / 5 / 10 / không giới hạn). Để cung cấp cho khách hàng một số lượng chỗ ngồi trong nhóm chính xác — 2, 7, 15, hoặc bất kỳ số nào — hãy đặt usage_limits.team_seats_limit thay thế. Giá trị này sẽ ghi đè lên các thiết lập sẵn và nền tảng sẽ thực thi nó trên mọi lời mời, thêm trực tiếp và chấp nhận lời mời: khi đạt đến giới hạn, các lời mời tiếp theo sẽ bị từ chối ở phía máy chủ.

• Một số nguyên dương là giới hạn chính xác.
• 0 nghĩa là các thành viên nhóm không được bao gồm — khách hàng không thể mời bất kỳ ai.
• -1 nghĩa là không giới hạn.
• null xóa giới hạn tùy chỉnh và quay lại sử dụng bất kỳ thiết lập sẵn team_seats_* nào có trong danh sách tính năng.

Việc giảm giới hạn không bao giờ xóa các thành viên nhóm hiện có; nó chỉ ngăn chặn việc thêm thành viên mới.

curl -X PUT "https://api.dmchamp.com/v1/subaccounts/SUB_ACCOUNT_UID/limits" \
  -H "X-API-Key: YOUR_AGENCY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "usageLimits": { "team_seats_limit": 7 }
  }'

Bạn cũng có thể thiết lập nó tại thời điểm tạo: POST /v1/subaccounts chấp nhận usage_limits.team_seats_limit với cùng ngữ nghĩa. Để đọc giá trị hiện tại, hãy lấy tài khoản phụ với GET /v1/subaccounts?email=... và xem usage_limits.team_seats_limit (vắng mặt/null = các giá trị đặt trước sẽ quyết định). Cùng một endpoint đó cũng cập nhật credits, monthly_credits, roll_over_to_next_month, rollover_cap_months, rollover_expiry_days và byok_monthly_limit_usd — chỉ gửi các khóa bạn muốn thay đổi.

Cách tính năng này tương tác với giới hạn số lượng chỗ ngồi của gói SaaS. Các gói SaaS của bạn có thể có hạn mức số lượng chỗ ngồi riêng (được thiết lập trong trình chỉnh sửa gói — xem Số lượng chỗ ngồi của nhóm trong một gói), hạn mức này sẽ được áp dụng tự động khi khách hàng đăng ký. Giới hạn bạn đặt thông qua endpoint này được tính là một khoản cấp thủ công: việc mua một gói sẽ thay thế giới hạn đó bằng hạn mức số lượng chỗ ngồi của chính gói đó (việc mua hàng đó là một lựa chọn gói rõ ràng), nhưng các lần gia hạn hàng tháng tự động sẽ không bao giờ ghi đè lên giới hạn thủ công — vì vậy, một ngoại lệ một lần mà bạn cấp cho khách hàng sẽ vẫn tồn tại sau chu kỳ thanh toán của họ. Việc xóa giới hạn thủ công bằng null sẽ trả lại quyền kiểm soát trường này cho gói vào lần gia hạn tiếp theo.

Giới hạn những gì khách hàng mang theo giữa các lần gia hạn. Hai khóa usage_limits nữa nằm cạnh roll_over_to_next_month. Cả hai đều được POST /v1/subaccounts chấp nhận tại thời điểm tạo, và null sẽ xóa một trong hai.

Nếu không được thiết lập, cả hai sẽ quay lại gói của khách hàng; một giá trị được gửi ở đây sẽ ghi đè lên giá trị của gói. Chỉ các khoản tín dụng định kỳ (phụ cấp hàng tháng và tín dụng gói) mới chịu sự điều chỉnh này: các khoản nạp thêm, tự động nạp lại và bổ sung một lần không bao giờ bị giới hạn hoặc hết hạn. Mỗi lần cắt giảm được ghi vào lịch sử tín dụng của khách hàng dưới dạng Điều chỉnh tín dụng giới hạn chuyển tiếp hoặc Điều chỉnh tín dụng hết hạn và không bao giờ được tính là mức sử dụng. Các giá trị tương đương ở cấp độ gói là rollover_cap_months và rollover_expiry_days trên một bậc giá — xem Các trường trên một bậc giá và Giới hạn những gì được chuyển tiếp.

Thiết lập giá và chính sách AI cho mỗi khách hàng #

PUT /v1/subaccounts/{subAccountUid}/max-tier · /ai-tiers · /max-rate · /action-pricing · /insider-rate · /locked-bot-fields · /notifications · /zero-credit-reply

Tám công tắc bổ sung cho mỗi khách hàng, cùng với /limits, /features và /menu-visibility ở trên. Mỗi công tắc lấy uid của tài khoản phụ trong URL (không có tham số sub_account_id body/query — mục tiêu đã được đặt tên trong đường dẫn) và được giới hạn theo cùng một cách: khóa đại lý của bạn và tài khoản phụ phải thuộc về đại lý của bạn.

Các mô hình AI mà khách hàng có thể sử dụng

curl -X PUT "https://api.dmchamp.com/v1/subaccounts/SUB_ACCOUNT_UID/max-tier" \
  -H "X-API-Key: YOUR_AGENCY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": true }'

{ "enabled": boolean } cho phép khách hàng tham gia (hoặc rời khỏi) cấp Max AI — cơ sở hạ tầng của chúng tôi theo giá niêm yết của nền tảng. Việc bật tính năng này cho khách hàng BYOK sẽ thay đổi chi phí AI của họ từ “miễn phí trên khóa của riêng tôi” thành “tính phí vào nhóm tín dụng của tôi”, vì vậy đây là một quyết định có chủ ý cho mỗi khách hàng thay vì là mặc định toàn đại lý.

Để hạn chế CÁC cấp độ mà chiến dịch và Trợ lý của khách hàng có thể chọn (thay vì chỉ chặn Max), hãy sử dụng ai-tiers:

curl -X PUT "https://api.dmchamp.com/v1/subaccounts/SUB_ACCOUNT_UID/ai-tiers" \
  -H "X-API-Key: YOUR_AGENCY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "allowed_ai_tiers": ["standard", "economy"] }'

allowed_ai_tiers là một mảng được rút ra từ standard, economy, max, mini — nó THAY THẾ danh sách cho phép của khách hàng. Gửi null (hoặc []) để xóa hạn chế và cho phép họ chọn bất kỳ cấp độ nào. Điều này quan trọng vì một tài khoản phụ chọn cấp độ AI của riêng mình sẽ chi tiêu từ nhóm tín dụng của bạn, vì vậy đây là đòn bẩy để ghim các mô hình mà khách hàng đại lý có thể sử dụng để tăng hóa đơn của bạn.

Một phản hồi giữ chỗ khi khách hàng hết tín dụng

curl -X PUT "https://api.dmchamp.com/v1/subaccounts/SUB_ACCOUNT_UID/zero-credit-reply" \
  -H "X-API-Key: YOUR_AGENCY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": true, "message": "Thanks for your message, we will get back to you shortly." }'

Khi số dư của khách hàng (hoặc nhóm của bạn) trống, AI không thể trả lời và người liên hệ sẽ không nhận được gì. Với enabled: true, mọi người liên hệ viết thư trong thời gian ngừng hoạt động sẽ nhận được message một lần (tối đa 500 ký tự, được gửi nguyên trạng trên mọi kênh), và AI sẽ trả lời các cuộc trò chuyện đó một cách thực sự sau khi có lại tín dụng. enabled: false giữ lại văn bản đã lưu để sử dụng sau; enabled: false không có message sẽ xóa cài đặt. Công tắc tương tự như Phản hồi giữ chỗ khi hết tín dụng trong modal Chỉnh sửa của tài khoản phụ — xem Một phản hồi giữ chỗ khi khách hàng hết tín dụng.

Khách hàng trả bao nhiêu cho mỗi hành động AI và phí đánh dấu WhatsApp

Hai cách để thiết lập tỷ lệ khách hàng của bạn, từ đơn giản nhất đến chi tiết nhất:

curl -X PUT "https://api.dmchamp.com/v1/subaccounts/SUB_ACCOUNT_UID/max-rate" \
  -H "X-API-Key: YOUR_AGENCY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "rate": 0.35 }'

rate là giá bằng tín dụng mà số dư RIÊNG của tài khoản phụ tiêu tốn cho mỗi hành động AI mô hình Max — mức đánh dấu khách hàng của bạn trên mức mà nhóm của bạn thực sự trả. null xóa ghi đè trở lại giá niêm yết của nền tảng. Tỷ lệ này phải ít nhất bằng chi phí của một hành động Max đối với nhóm của riêng bạn (vì vậy bạn không bao giờ có thể định giá khách hàng thấp hơn chi phí của mình) và không quá 10 tín dụng; một yêu cầu nằm ngoài phạm vi đó sẽ bị từ chối kèm theo mức sàn được tính toán trong thông báo lỗi.

Để định giá theo loại hành động thay vì một mức giá Max cố định, hãy sử dụng action-pricing:

curl -X PUT "https://api.dmchamp.com/v1/subaccounts/SUB_ACCOUNT_UID/action-pricing" \
  -H "X-API-Key: YOUR_AGENCY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "actionPricing": {
      "AI_MESSAGE": 0.6,
      "CHAT_SUMMARY": 0.15,
      "wa_carrier_multiplier": null
    }
  }'

actionPricing là một HỢP NHẤT vào bản đồ hiện có của khách hàng — một khóa bạn không đề cập đến sẽ được giữ nguyên như cũ và null sẽ hủy đặt khóa đó trở lại mặc định. Các khóa được công nhận:

Tỷ lệ cho mỗi hành động phải là một số lớn hơn 0 và tối đa là 10; wa_carrier_multiplier phải ít nhất là 1 (không giảm giá dưới giá vốn) và tối đa là 10. Việc gửi một khóa không được nhận dạng hoặc một giá trị nằm ngoài phạm vi sẽ từ chối TOÀN BỘ yêu cầu và nêu tên mọi khóa vi phạm, vì vậy lỗi đánh máy sẽ không bao giờ âm thầm lưu một mức giá không thực sự được áp dụng.

Nếu bạn là thành viên Champions Circle, insider-rate sẽ chuyển mức giảm giá 20% Max/Lead Finder của bạn cho một khách hàng thay vì áp dụng cho toàn bộ đại lý:

curl -X PUT "https://api.dmchamp.com/v1/subaccounts/SUB_ACCOUNT_UID/insider-rate" \
  -H "X-API-Key: YOUR_AGENCY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": true }'

Việc bật tính năng này yêu cầu tài khoản đại lý của chính bạn phải có tư cách thành viên Circle; việc tắt tính năng này thì không, vì vậy một thành viên đã hết hạn vẫn luôn có thể hạ mức ưu đãi của khách hàng xuống.

Khóa các phần trong sổ tay của khách hàng

curl -X PUT "https://api.dmchamp.com/v1/subaccounts/SUB_ACCOUNT_UID/locked-bot-fields" \
  -H "X-API-Key: YOUR_AGENCY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "locked_bot_fields": ["instructions", "rules"] }'

locked_bot_fields là một mảng được lấy từ instructions, goal, rules, personality, conclude_unless — nó THAY THẾ danh sách đã khóa của khách hàng. Một phần đã khóa sẽ bị từ chối ở phía máy chủ nếu chính TÀI KHOẢN PHỤ cố gắng thay đổi nó (trực tiếp hoặc bằng khóa API), trong khi bạn (thông qua sub_account_id) và chế độ xem quản trị bảng điều khiển của khách hàng vẫn có thể chỉnh sửa mọi thứ. Gửi null (hoặc []) để mở khóa mọi thứ. Hữu ích cho các khách hàng sử dụng dịch vụ trọn gói nơi bạn sở hữu sổ tay và được đánh giá dựa trên kết quả.

Đặt tùy chọn thông báo của khách hàng thay mặt cho họ

curl -X PUT "https://api.dmchamp.com/v1/subaccounts/SUB_ACCOUNT_UID/notifications" \
  -H "X-API-Key: YOUR_AGENCY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "notifications": {
      "settings": {
        "credit_alerts": { "enabled": true, "channels": ["email", "in_app"] },
        "new_contacts": { "enabled": false }
      }
    }
  }'

notifications thay thế toàn bộ tập hợp tùy chọn thông báo của khách hàng (không phải là hợp nhất theo từng khóa — hãy gửi mọi danh mục bạn muốn giữ lại, khớp với cách trang Cài đặt của tài khoản phụ lưu lại). Mỗi danh mục trong settings chấp nhận enabled (boolean) và tối đa ba channels từ email, in_app, webhook. Gửi null để đặt lại về mặc định của nền tảng.

Tất cả bảy endpoint đều phản hồi { "success": true, "data": { "subAccountUid": "...", ...the field(s) you set... } } và được ghi nhật ký kiểm toán với giá trị trước/sau. Các lỗi phổ biến: 403 nếu tài khoản của bạn không phải là Agency/Dev hoặc tài khoản phụ không thuộc quyền quản lý của bạn, 400 nếu đó không phải là tài khoản phụ của đại lý hoặc giá trị nằm ngoài phạm vi cho phép.

Tạm dừng một khách hàng đã đình chỉ đăng ký của họ #

POST /v1/subaccounts/{subAccountUid}/pause · POST /v1/subaccounts/{subAccountUid}/unpause

Khi một khách hàng đình chỉ đăng ký với bạn, hãy tạm dừng tài khoản của họ thay vì xóa nó: mọi thứ họ gửi sẽ dừng lại ngay lập tức — tin nhắn gửi đi, tin nhắn quảng bá, phản hồi AI trên mọi kênh — và khi họ đăng nhập, họ sẽ thấy màn hình khóa Tài khoản đã tạm dừng (với thông báo tùy chọn của bạn) thay vì ứng dụng. Không có gì bị xóa hoặc ngắt kết nối: các nhân viên, chiến dịch, kênh đã kết nối, danh bạ và lịch sử trò chuyện đều giữ nguyên trạng thái, vì vậy việc bỏ tạm dừng sẽ đưa khách hàng trở lại chính xác nơi họ đã dừng lại — không cần phải thiết lập lại.

cURL

curl -X POST "https://api.dmchamp.com/v1/subaccounts/SUB_ACCOUNT_UID/pause" \
  -H "X-API-Key: YOUR_AGENCY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "message": "Your account is on hold — contact us to reactivate it.", "reason": "Subscription suspended per client email" }'

Phản hồi

{
  "success": true,
  "data": {
    "subAccountUid": "SUB_ACCOUNT_UID",
    "paused": true,
    "level": "hard_blocked"
  }
}

Khi khách hàng quay lại, POST /v1/subaccounts/SUB_ACCOUNT_UID/unpause (không có nội dung) sẽ gỡ bỏ màn hình khóa — việc gửi tin nhắn và phản hồi AI sẽ tiếp tục ngay lập tức.

Những điều cần biết:

• Đây là trạng thái tương tự như nút gạt Chặn cứng (Hard blocked) trên bảng điều khiển (Chặn / Tạm dừng Tài khoản phụ) — một khách hàng bị tạm dừng qua API sẽ hiển thị là bị chặn trên bảng điều khiển và ngược lại, và việc bỏ tạm dừng sẽ xóa trạng thái chặn được đặt từ cả hai phía. Trạng thái hiện tại có thể đọc được từ trường agency_block trên GET /v1/subaccounts (level của "none", "soft_blocked" hoặc "hard_blocked").
• Cả hai lệnh gọi đều là lũy đẳng (idempotent). Việc tạm dừng một khách hàng đã bị tạm dừng chỉ làm mới thông báo, lý do và dấu thời gian; việc bỏ tạm dừng một khách hàng đang hoạt động sẽ không thay đổi gì cả.
• Khách hàng không được gửi email tự động — nhiều đại lý sử dụng thương hiệu riêng (white-label), vì vậy việc thông báo cho khách hàng là tùy thuộc vào bạn.
• Việc thanh toán DM Champ của riêng bạn không bị ảnh hưởng. Việc tạm dừng một khách hàng chỉ ảnh hưởng đến mối quan hệ của bạn với họ.
• Các trợ lý AI cũng có thể thực hiện việc này: máy chủ MCP cung cấp các điểm cuối này dưới dạng công cụ pause_subaccount và unpause_subaccount.

Cấp hoặc khấu trừ tín dụng trực tiếp #

POST /v1/subaccounts/credits

Thêm hoặc xóa một số lượng tín dụng chính xác khỏi số dư của một tài khoản phụ — tương đương API của việc điều chỉnh tín dụng thủ công trên bảng điều khiển. Đây là thay đổi số dư một lần, khác với các cài đặt định kỳ monthly_credits, roll_over_to_next_month, rollover_cap_months và rollover_expiry_days trên PUT /v1/subaccounts/{subAccountUid}/limits.

Đây là endpoint duy nhất trên trang này xác định tài khoản phụ bằng email thay vì sub_account_id.

cURL

curl -X POST "https://api.dmchamp.com/v1/subaccounts/credits" \
  -H "X-API-Key: YOUR_AGENCY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "email": "client@example.com", "amount": 500, "description": "Q3 bonus credits" }'

Phản hồi

{
  "success": true,
  "data": {
    "email": "client@example.com",
    "previous_balance": 1200,
    "adjustment": 500,
    "new_balance": 1700
  }
}

Một amount âm làm cho số dư xuống dưới 0 sẽ bị từ chối với 400, cho bạn biết số dư khả dụng và số tiền bạn đã cố gắng khấu trừ. Nếu khách hàng đang sử dụng thanh toán Stripe của riêng họ (chế độ đại lý), một số tiền được thêm vào cũng được tính là tín dụng họ đã mua, vì vậy nó tồn tại sau lần đặt lại hàng tháng tiếp theo giống như cách một khoản nạp tiền thực sự sẽ làm; đối với một khách hàng được phân bổ tiêu chuẩn, nó được coi là một phần của phụ cấp định kỳ của họ. Dù bằng cách nào, chúng là một khoản bổ sung một lần, vì vậy giới hạn chuyển tiếp hoặc ngày hết hạn được đặt trên tài khoản (hoặc gói của nó) không bao giờ cắt giảm chúng — chỉ phụ cấp định kỳ và tín dụng gói mới chịu sự điều chỉnh đó.

Đọc các cuộc hội thoại của tài khoản phụ #

GET /v1/subaccounts/{subAccountUid}/chats · GET /v1/subaccounts/{subAccountUid}/chats/{contactId}/messages

Cho phép bạn xây dựng chế độ xem giám sát hoặc hỗ trợ các cuộc hội thoại của khách hàng mà không cần đăng nhập vào tài khoản của họ. Trước tiên, hãy liệt kê danh sách liên hệ của họ cùng bản xem trước của tin nhắn mới nhất, sau đó đọc toàn bộ lịch sử tin nhắn của một liên hệ.

Liệt kê liên hệ

curl "https://api.dmchamp.com/v1/subaccounts/SUB_ACCOUNT_UID/chats?apiKey=YOUR_AGENCY_API_KEY&pageSize=25"

Phản hồi

{
  "success": true,
  "data": {
    "contacts": [
      {
        "contactId": "contact456",
        "firstName": "Jamie",
        "lastName": "Lee",
        "phoneNumber": "+14155551234",
        "email": "jamie@example.com",
        "channel": "whatsapp",
        "lastActivityAt": "2026-08-30T14:22:00.000Z",
        "lastMessage": { "body": "Thanks, that fixed it!", "direction": "inbound", "timestamp": "2026-08-30T14:22:00.000Z" },
        "isBotActive": true,
        "markChatClosed": false
      }
    ],
    "subAccountName": "Client Co",
    "subAccountEmail": "client@example.com",
    "hasMore": true,
    "lastActivityAt": "2026-08-30T14:22:00.000Z"
  }
}

Các liên hệ được sắp xếp theo hoạt động gần đây nhất trước. Tiếp tục phân trang với lastActivityAt trong khi hasMore là true.

Đọc tin nhắn của một liên hệ

curl "https://api.dmchamp.com/v1/subaccounts/SUB_ACCOUNT_UID/chats/contact456/messages?apiKey=YOUR_AGENCY_API_KEY&pageSize=30"

Phản hồi

{
  "success": true,
  "data": {
    "messages": [
      {
        "messageId": "msg789",
        "body": "Thanks, that fixed it!",
        "direction": "inbound",
        "timestamp": "2026-08-30T14:22:00.000Z",
        "status": "received",
        "channel": "whatsapp",
        "botReply": false,
        "mediaUrl": null,
        "mediaContentType": null,
        "name": "Jamie Lee",
        "role": null
      }
    ],
    "contactInfo": { "firstName": "Jamie", "lastName": "Lee", "phoneNumber": "+14155551234", "channel": "whatsapp" },
    "hasMore": false,
    "oldestTimestamp": "2026-08-30T14:22:00.000Z"
  }
}

Tin nhắn được trả về theo thứ tự mới nhất trước; lật ngược lịch sử bằng beforeTimestamp.

Đọc mức sử dụng tín dụng và tình trạng chiến dịch trên toàn bộ danh mục của bạn #

GET /v1/subaccounts/credit-usage · GET /v1/subaccounts/campaign-status

Hai bản tổng hợp kiểu bảng điều khiển trên mọi tài khoản phụ mà bạn quản lý, giúp bạn tự xây dựng báo cáo đại lý thay vì phải nhấp vào từng khách hàng một.

Mức sử dụng tín dụng

curl "https://api.dmchamp.com/v1/subaccounts/credit-usage?apiKey=YOUR_AGENCY_API_KEY&from=2026-08-01&to=2026-08-31"

{
  "success": true,
  "data": {
    "subAccounts": [
      {
        "subAccountId": "abc123def456",
        "subAccountName": "Client Co",
        "subAccountEmail": "client@example.com",
        "totalCreditsUsed": 842,
        "totalCostUsd": 3.15,
        "byReason": { "AI reply": 620, "Chat summary": 80 },
        "topCampaigns": [{ "campaignName": "Inbound Leads", "creditsUsed": 500 }]
      }
    ],
    "totals": { "totalCreditsUsed": 842, "totalCostUsd": 3.15, "totalRecords": 214 },
    "dateRange": { "from": "2026-08-01", "to": "2026-08-31" },
    "hasMore": false,
    "lastTimestamp": null
  }
}

Truyền subAccountId và phản hồi tương tự cũng sẽ mang theo records: các khoản phí riêng lẻ với amount, reason, campaignName, contactName và timestamp. Khách hàng chi tiêu bằng khóa BYOK của riêng họ thay vì tín dụng của bạn sẽ bị ẩn các số liệu chi phí/token (costsRedacted: true) — đó là dữ liệu đo lường chi phí nền tảng, không phải thứ để hiển thị cho người xem đại lý.

Trạng thái chiến dịch

curl "https://api.dmchamp.com/v1/subaccounts/campaign-status?apiKey=YOUR_AGENCY_API_KEY&pageSize=20"

{
  "success": true,
  "data": {
    "totalSubAccounts": 34,
    "subAccountsWithIssues": 3,
    "totalLiveCampaigns": 51,
    "totalPausedCampaigns": 6,
    "subAccounts": [
      {
        "userId": "abc123def456",
        "email": "client@example.com",
        "displayName": "Jamie Lee",
        "businessName": "Client Co",
        "totalCampaigns": 2,
        "liveCampaigns": 1,
        "pausedCampaigns": 1,
        "hasIssues": true,
        "issueDetails": ["1 campaign paused"],
        "lastCampaignActivity": "2026-08-29T09:00:00.000Z"
      }
    ],
    "hasMore": true,
    "lastDocumentId": "abc123def456",
    "pageSize": 20
  }
}

Cờ hasIssues / issueDetails đánh dấu các tài khoản phụ cần lưu ý — ví dụ: một chiến dịch bị tạm dừng hoặc chiến dịch không có kênh nào được định tuyến đến. Hãy sử dụng tính năng này để xây dựng bảng điều khiển kiểm tra tình trạng cho toàn bộ danh sách thay vì phải mở từng khách hàng để phát hiện chiến dịch bị đình trệ.

Để biết thông tin nhắn tin theo chuỗi thời gian và hoạt động tín dụng của mọi khách hàng (một chuỗi dữ liệu sẵn sàng để lập biểu đồ thay vì ảnh chụp nhanh tại một thời điểm), hãy xem GET /analytics/agency-rollup trong hướng dẫn API Phân tích.

Cung cấp một tài khoản khách hàng đã được thiết lập sẵn #

PUT /v1/snapshots/default · POST /v1/snapshots/{snapshotId}/apply

Một snapshot là một mẫu có thể tái sử dụng: một hoặc nhiều tác nhân AI cùng với cơ sở kiến thức, công cụ và phương tiện của chúng, được ghi lại từ chính tài khoản của bạn. Hai điểm cuối (endpoint) sẽ đưa nó vào quy trình cung cấp dịch vụ của bạn.

Tự động — mọi khách hàng mới đều có sẵn. Hãy gắn dấu sao cho một snapshot làm mặc định một lần, và mọi tài khoản bạn tạo kể từ đó sẽ được cài đặt sẵn snapshot này. Điều này áp dụng cho các tài khoản được tạo thông qua POST /v1/subaccounts, các tài khoản bạn tạo trong bảng điều khiển và các tài khoản được tạo tự động khi khách hàng thanh toán qua liên kết thanh toán của bạn.

Trước tiên, hãy tìm id của snapshot:

curl "https://api.dmchamp.com/v1/snapshots" \
  -H "X-API-Key: YOUR_AGENCY_API_KEY"

Sau đó, đặt nó làm mặc định:

curl -X PUT "https://api.dmchamp.com/v1/snapshots/default" \
  -H "X-API-Key: YOUR_AGENCY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "snapshot_id": "SNAPSHOT_ID" }'

Đó là toàn bộ quá trình tích hợp. Gửi {"snapshot_id": null} để tắt nó đi. Bạn có thể thực hiện tương tự từ bảng điều khiển bằng cách nhấp vào dấu sao trên trang Snapshots.

Để đọc lại những gì hiện đang được gắn dấu sao (ví dụ: trước khi tập lệnh cấp phép quyết định có đặt một cái hay không), GET /v1/snapshots/default sẽ trả về { "success": true, "data": { "default_snapshot_id": "SNAPSHOT_ID" } } — null khi không có gì được gắn dấu sao. GET /v1/snapshots (được sử dụng để tìm id ở trên) trả về cùng một default_snapshot_id cùng với mảng snapshots đầy đủ, vì vậy hầu hết các tích hợp chỉ cần một lệnh gọi này. Các trường đối tượng ảnh chụp nhanh đầy đủ nằm trong hướng dẫn Ảnh chụp nhanh.

Theo yêu cầu — cài đặt vào một tài khoản. Hữu ích cho việc giới thiệu khách hàng hiện tại hoặc để cung cấp cho khách hàng một mẫu thứ hai sau này.

curl -X POST "https://api.dmchamp.com/v1/snapshots/SNAPSHOT_ID/apply" \
  -H "X-API-Key: YOUR_AGENCY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "sub_account_id": "SUB_ACCOUNT_UID" }'

Bỏ qua sub_account_id và nó sẽ cài đặt vào tài khoản đại lý của chính bạn. Giống như các điểm cuối /subaccounts, các điểm cuối này chỉ định tài khoản đích trong đường dẫn hoặc nội dung thay vì thông qua tham số sub_account_id mặc định.

Những điều cần biết trước khi bạn xây dựng dựa trên nó:

• Các tác nhân được cài đặt sẽ bắt đầu ở trạng thái tạm dừng. Hãy kết nối các kênh của khách hàng trước, sau đó kích hoạt tác nhân. Điều này đúng cho cả quy trình tự động và theo yêu cầu.
• Việc cung cấp dịch vụ không bao giờ thất bại do snapshot. Nếu quá trình cài đặt không thể hoàn tất, tài khoản khách hàng vẫn được tạo và có thể sử dụng — nó chỉ đơn giản là trống và bạn có thể áp dụng snapshot sau đó.
• Các kênh, lịch và kết nối OAuth không bao giờ bị sao chép. Mỗi tài khoản sẽ kết nối riêng. Các công cụ sử dụng khóa API thông thường vẫn hoạt động ngay lập tức.
• Áp dụng hai lần sẽ tạo ra bản sao thứ hai. Không có gì bị ghi đè.

Tự xây dựng template thông qua API #

POST /v1/snapshots · tác nhân, hàm tùy chỉnh và phương tiện thông qua API

Phần trên mô tả cách phân phối một bản chụp (snapshot) đã được tạo trong bảng điều khiển. Phần soạn thảo cũng được công khai, vì vậy toàn bộ quy trình — thiết lập cấu hình chính một lần, chụp lại, và chuyển cho mọi khách hàng — đều có thể chạy bằng mã nguồn.

Các thành phần, theo thứ tự mà một tập lệnh cung cấp (provisioning script) sử dụng:

1. Tạo các hàm tùy chỉnh của bạn. POST /v1/custom-functions tạo một hàm; GET /v1/custom-functions liệt kê các hàm bạn có, và GET, PUT cùng DELETE trên /v1/custom-functions/{customFunctionId} dùng để đọc, cập nhật và xóa một hàm. POST /v1/custom-functions/test chạy thử nghiệm (dry-run) một định nghĩa trước khi bạn lưu nó.
2. Tạo và định hình tác nhân. POST /v1/agents tạo tác nhân, PUT /v1/agents/{agentId} cập nhật nó, và PATCH /v1/agents/{agentId}/active với { "active": false } giữ cho nó ở trạng thái tạm dừng trong khi bạn làm việc (cùng lệnh gọi đó với true sẽ đưa nó vào hoạt động). GET /v1/agents liệt kê các tác nhân.
3. Cung cấp khả năng cho tác nhân. POST /v1/agents/{agentId}/custom-functions với { "custom_function_id": "..." } đính kèm một hàm vào tác nhân; lệnh DELETE /v1/agents/{agentId}/custom-functions/{customFunctionId} tương ứng sẽ tách nó ra.
4. Lấp đầy thư viện phương tiện. POST /v1/agents/{agentId}/media-library tải lên một mục (JSON với base64Data, mimeType, title, description); GET liệt kê các mục của tác nhân, và PATCH/DELETE trên /{itemId} cập nhật hoặc xóa một mục.
5. Chụp lại thành một bản snapshot.

curl -X POST "https://api.dmchamp.com/v1/snapshots" \
  -H "X-API-Key: YOUR_AGENCY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Master setup v1",
    "agent_ids": ["AGENT_ID"],
    "include_knowledge": true,
    "include_tools": true,
    "include_media": true
  }'

Từ đó, quy trình sẽ giống như phần trước: đánh dấu sao (star) làm mặc định để mọi khách hàng mới đều có sẵn, hoặc áp dụng theo yêu cầu. Các công việc quản lý đi kèm: PATCH /v1/snapshots/{snapshotId} với { "name": "..." } đổi tên một bản chụp, DELETE /v1/snapshots/{snapshotId} xóa một bản chụp (và bỏ đánh dấu sao nếu đó là bản mặc định), và GET /v1/snapshots/apply-targets liệt kê mọi tài khoản mà bạn có thể cài đặt vào.

Các điểm cuối (endpoint) của tác nhân, hàm tùy chỉnh và phương tiện đều chấp nhận sub_account_id, vì vậy các lệnh gọi tương tự cũng có thể duy trì một tác nhân trực tiếp bên trong tài khoản của một khách hàng. Các lệnh gọi snapshot luôn hoạt động trên tài khoản đại lý của bạn — template nằm cùng với bạn. Lược đồ yêu cầu và phản hồi đầy đủ cho tất cả các mục này có trong Tài liệu tham khảo API.

Quản lý các cấp giá của bạn thông qua API #

GET /v1/agency/pricing-tiers · POST /v1/agency/pricing-tiers · PATCH /v1/agency/pricing-tiers/{tierIndex} · DELETE /v1/agency/pricing-tiers/{tierIndex}

Các gói bạn bán trong Chế độ SaaS → Các cấp giá có thể được đọc và thay đổi từ mã nguồn, vì vậy bảng quản trị hoặc tập lệnh cấp phép của riêng bạn có thể thêm gói, điều chỉnh giá hoặc cung cấp liên kết thanh toán mà không cần bất kỳ ai mở bảng điều khiển. Xác thực bằng khóa API đại lý của bạn giống như mọi lệnh gọi khác trên trang này; các endpoint này ở cấp đại lý, vì vậy chúng không yêu cầu sub_account_id. Mọi thao tác ghi đều chạy cùng quy trình xác thực và đồng bộ hóa sản phẩm-giá Stripe giống như khi lưu trên bảng điều khiển, vì vậy một gói được tạo ở đây không khác gì gói bạn thiết lập thủ công.

Liệt kê các cấp giá của bạn #

curl "https://api.dmchamp.com/v1/agency/pricing-tiers" \
  -H "X-API-Key: YOUR_AGENCY_API_KEY"

Phản hồi

{
  "success": true,
  "data": {
    "tiers": [
      {
        "tierIndex": 0,
        "credits": 1000,
        "price_cents": 2900,
        "currency": "usd",
        "label": "Starter",
        "billing_interval": "month",
        "trial_days": 14,
        "trial_credits": 250,
        "trial_card_required": false,
        "trial_hard_expiry": true,
        "stripe_price_id": "price_1PxAbC…",
        "stripe_product_id": "prod_QxAbC…",
        "checkout_url": "https://app.yourdomain.com/v1/checkout?id=YOUR_AGENCY_UID&tierIndex=0"
      }
    ],
    "count": 1,
    "max_tiers": 20
  }
}

Mỗi cấp giá trả về kèm theo tierIndex — vị trí của nó trong danh sách Gói của bạn, đây là cách ba lệnh gọi khác truy cập vào nó — và một checkout_url sẵn sàng để chia sẻ, giống như liên kết mà tab Thanh toán cung cấp cho bạn, đã trỏ đến tên miền white label mà gói đó được bán trên đó.

Thêm một cấp giá #

Phần thân là một đối tượng cấp giá; nó được thêm vào cuối danh sách của bạn.

curl -X POST "https://api.dmchamp.com/v1/agency/pricing-tiers" \
  -H "X-API-Key: YOUR_AGENCY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Starter",
    "credits": 1000,
    "price_cents": 2900,
    "currency": "usd",
    "billing_interval": "month",
    "trial_days": 14,
    "trial_credits": 250,
    "trial_card_required": false,
    "trial_hard_expiry": true,
    "features": ["channels_3", "channel_whatsapp_web", "webhooks"]
  }'

Phản hồi mang theo cấp giá đã tạo, bao gồm tierIndex mà nó được đặt vào và checkout_url của nó.

Chỉnh sửa một cấp giá #

Chỉ gửi các trường bạn muốn thay đổi; mọi thứ khác trên gói sẽ được giữ nguyên như cũ.

curl -X PATCH "https://api.dmchamp.com/v1/agency/pricing-tiers/0" \
  -H "X-API-Key: YOUR_AGENCY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "price_cents": 3900, "trial_hard_expiry": true }'

Một trường mà API không nhận dạng được sẽ bị từ chối thay vì bị bỏ qua, và lỗi sẽ nêu tên trường đó — vì vậy lỗi đánh máy sẽ không bao giờ âm thầm ghi đè một cài đặt trông có vẻ đang hoạt động nhưng thực tế không làm gì cả. Việc thay đổi giá, tín dụng, đơn vị tiền tệ hoặc chu kỳ thanh toán sẽ tạo ra một mức giá mới trong Stripe của bạn; những khách hàng đã đăng ký sẽ vẫn giữ nguyên gói họ đã đăng ký.

Xóa một cấp giá #

curl -X DELETE "https://api.dmchamp.com/v1/agency/pricing-tiers/2" \
  -H "X-API-Key: YOUR_AGENCY_API_KEY"

Quy tắc tương tự như trên bảng điều khiển: một gói vẫn còn người đăng ký hoạt động thì không thể xóa được. Yêu cầu sẽ bị từ chối, cho bạn biết có bao nhiêu người đăng ký đang sử dụng gói đó — hãy hủy hoặc chuyển đổi họ trước. Một lệnh xóa thành công sẽ phản hồi lại các cấp giá còn lại của bạn, đã được đánh số lại.

Các trường trên một cấp giá #

Các trường dùng thử chỉ có ý nghĩa đối với gói có dùng thử: lưu một tầng với trial_days: 0 và chúng sẽ bị loại bỏ. ID sản phẩm và giá Stripe của gói được quản lý cho bạn và không thể thiết lập thủ công.

Ba điều cần lưu ý:

• Chỉ số tầng là vị trí, không phải ID vĩnh viễn. Việc xóa một gói sẽ đẩy mọi gói phía sau nó lên một vị trí, vì vậy hãy lấy lại danh sách sau bất kỳ thay đổi nào — và sao chép lại các liên kết thanh toán mà bạn đã xuất bản, giống hệt như cách bạn làm sau khi xóa một gói trong bảng điều khiển.
• Chế độ SaaS phải được thiết lập trước. Các điểm cuối này cần một tài khoản đại lý với tính năng gắn nhãn trắng (white labeling) và khóa Stripe đã được lưu; nếu không có, sẽ không có tài khoản Stripe nào để sản phẩm và giá của gói tồn tại.
• Giới hạn là hai mươi gói, giống như trong bảng điều khiển. Trường max_tiers trong phản hồi danh sách sẽ cho bạn biết giới hạn hiện tại.

Các lược đồ yêu cầu và phản hồi đầy đủ nằm trong Tài liệu tham khảo API, mục Đại lý.

Thiết lập giá mỗi tín dụng của bạn thông qua API #

GET /v1/agency/credit-price · PATCH /v1/agency/credit-price

Giá mà khách hàng trả cho việc nạp thêm tín dụng ad-hoc (Chế độ SaaS → Định giá theo tín dụng) cũng có thể được đọc và thay đổi từ mã nguồn. Tính năng này được xây dựng cho trường hợp giá cần tự động thay đổi: một đại lý bán tín dụng bằng một loại tiền tệ nhưng tính phí bằng loại tiền tệ khác có thể để một tác vụ đã lên lịch sửa đổi giá khi tỷ giá hối đoái thay đổi, thay vì phải có người chỉnh sửa thủ công hàng tuần.

Đọc giá hiện tại #

curl "https://api.dmchamp.com/v1/agency/credit-price" \
  -H "X-API-Key: YOUR_AGENCY_API_KEY"

Phản hồi

{
  "success": true,
  "data": {
    "price_per_credit_cents": 125,
    "price_per_credit_currency": "brl",
    "note": "USD 0.25 per credit at our reference rate",
    "minimum_cents": 60
  }
}

minimum_cents là mức giá thấp nhất mà nền tảng cho phép đối với loại tiền tệ đó, vì vậy một tác vụ có thể kiểm tra giá mới trước khi gửi. Cả ba giá trị đều là null cho đến khi giá được thiết lập.

Thay đổi giá #

curl -X PATCH "https://api.dmchamp.com/v1/agency/credit-price" \
  -H "X-API-Key: YOUR_AGENCY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "price_per_credit_cents": 130, "currency": "brl" }'

Chỉ gửi những gì bạn muốn thay đổi. price_per_credit_cents là giá theo đơn vị tiền tệ nhỏ nhất (130 = R$1.30); currency là mã ISO viết thường; note là một dòng tùy chọn tối đa 200 ký tự được hiển thị cho khách hàng ngay dưới giá mỗi tín dụng trên trang Thanh toán của họ — rất hữu ích cho giá tham chiếu bằng loại tiền tệ khác, chẳng hạn như “0.25 USD mỗi tín dụng theo tỷ giá tham chiếu của chúng tôi”. Gửi "note": "" để xóa nó. Phản hồi có cùng định dạng với thao tác đọc ở trên, vì vậy một tác vụ có thể so sánh và bỏ qua việc ghi nếu không có gì thay đổi.

Các quy tắc tương tự như trong bảng điều khiển được áp dụng: giá không được thấp hơn mức tối thiểu của nền tảng cho loại tiền tệ đó và tài khoản cần có white labeling. Không giống như các endpoint cấp định giá, không cần khóa Stripe để đọc hoặc thay đổi giá trị này.

Cấp cho một tác vụ một khóa không thể làm gì khác #

Việc đưa toàn bộ khóa đại lý của bạn vào một trình lập lịch biểu là cấp quyền truy cập nhiều hơn mức cần thiết cho một bản cập nhật giá. Thay vào đó, hãy tạo một khóa có phạm vi giới hạn (scoped key) chỉ giới hạn trong khu vực Giá Tín dụng Đại lý: khóa đó có thể đọc và thay đổi giá mỗi tín dụng và không thể làm gì khác — nó không thể tác động đến các tài khoản phụ, gói dịch vụ, tín dụng hoặc kết nối Stripe của bạn.

curl -X POST "https://api.dmchamp.com/v1/api-keys" \
  -H "X-API-Key: YOUR_AGENCY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "label": "FX price updater", "scopes": { "read_only": false, "tags": ["Agency Credit Price"] } }'

Phản hồi sẽ chứa khóa mới trong api_key một lần duy nhất — nó sẽ không bao giờ được hiển thị lại, vì vậy hãy lưu trữ nó ngay lập tức. Đặt "read_only": true cho khóa chỉ cần đọc giá và thêm "expires_at" (một ngày theo chuẩn ISO) nếu bạn muốn nó tự động ngừng hoạt động. Chỉ khóa của chủ sở hữu tài khoản mới có thể tạo các khóa có phạm vi giới hạn; hãy liệt kê hoặc thu hồi chúng bằng GET /v1/api-keys và DELETE /v1/api-keys/{id}.

Cho phép tài khoản phụ đọc giá của bạn #

GET /v1/subaccounts/agency-pricing

Mọi điểm cuối khác trên trang này đều được gọi bằng khóa đại lý của bạn, tùy chọn nhắm mục tiêu đến khách hàng thông qua sub_account_id. Điểm cuối này thì ngược lại: nó được gọi bằng khóa API riêng của tài khoản phụ, không có sub_account_id, vì vậy trang nạp tiền của chính khách hàng (hoặc một tích hợp bạn xây dựng cho họ) có thể hiển thị mức phí bạn tính cho họ mà không bao giờ nhìn thấy tài khoản đại lý của bạn.

curl "https://api.dmchamp.com/v1/subaccounts/agency-pricing" \
  -H "X-API-Key: THE_SUB_ACCOUNTS_OWN_API_KEY"

Phản hồi

{
  "success": true,
  "data": {
    "tiers": [{ "credits": 1000, "price_cents": 2900, "currency": "usd" }],
    "price_per_credit_cents": 125,
    "price_per_credit_currency": "brl",
    "price_per_credit_note": "USD 0.25 per credit at our reference rate",
    "agency_display_name": "Client Co's Growth Partner"
  }
}

Điều này phản ánh chính xác những gì GET /v1/agency/pricing-tiers và GET /v1/agency/credit-price trả về cho bạn với tư cách là đại lý, trừ đi bất kỳ thứ gì mà khách hàng không cần xem (id Stripe, max_tiers, v.v.). Nó chỉ hoạt động đối với tài khoản thực sự là tài khoản phụ có liên kết với đại lý — việc gọi nó từ tài khoản đại lý của chính bạn sẽ trả về lỗi quyền truy cập.

Những điều cần lưu ý #

• Sử dụng khóa đại lý của bạn. Xác thực mọi lệnh gọi bằng khóa API của tài khoản đại lý — không phải của tài khoản phụ. Tham số sub_account_id là yếu tố chuyển hướng hành động.
• Tín dụng được trừ từ tài khoản phụ. Các giao dịch mua và phí định kỳ sẽ trừ vào số dư tín dụng của tài khoản phụ được nhắm mục tiêu, không phải của bạn.
• Lỗi 404 có nghĩa là “không phải tài khoản phụ của bạn.” Hãy kiểm tra kỹ id và đảm bảo rằng đó là tài khoản do bạn quản lý.
• Tham số này là tùy chọn ở mọi nơi được chấp nhận. Hãy bỏ qua nó và cùng một điểm cuối sẽ hoạt động trên tài khoản đại lý của bạn, vì vậy bạn có thể sử dụng lại một tích hợp cho cả hai.

Liên quan #

• Truy cập API — xác thực, URL cơ sở, lỗi, giới hạn tốc độ.
• Tài khoản phụ — liệt kê và quản lý các tài khoản bạn có thể nhắm mục tiêu.
• Tự động nạp tiền cho tài khoản phụ — cấp tín dụng cho tài khoản phụ thông qua webhook + API.
• API Chiến dịch — tạo, cập nhật và sao chép chiến dịch, bao gồm tài liệu tham khảo đầy đủ về trường.
• API Kết nối kênh — kết nối các kênh của khách hàng và định tuyến chúng đến một chiến dịch.
• Hướng dẫn API Phân tích (trong phần API) — tổng hợp tài khoản phụ của đại lý và mọi điểm cuối báo cáo khác.
• Ảnh chụp nhanh — những gì ảnh chụp nhanh ghi lại và cách xây dựng một ảnh chụp nhanh trong bảng điều khiển.