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ướ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ý 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 các tác nhân AI của họ, huấn luyện 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 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 cài đặt đó trên các công 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 công cụ, vì vậy bạn có thể tạo, thay đổi và gửi thay mặt cho 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ở tri thức (quét trang web và tải lên tài liệu), nhóm cơ sở tri thức, chương trình phát sóng, hàm tùy chỉnh, máy chủ MCP
• Liên hệ & CRM — liên hệ (bao gồm nhập dữ liệu), 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 white-label, SMS BYOK và các cài đặt tài khoản khác, phân tích, nhật ký lỗi

Trên mỗi yêu cầu 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 phục vụ cho 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 đến: các khoản phí cho phản hồi AI, tin nhắn, thẻ và số điện thoại của tài khoản phụ sẽ được trừ 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 đã nêu tên 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 tuân theo cùng một mô hình.
• Sao chép một Tác nhân giữa các tài khoản — POST /v1/subaccounts/agents/copy tự nêu tên 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ùng cách 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ý của bạn — 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.
• Thêm liên hệ vào danh sách hoặc xóa chúng khỏi danh sách: POST / DELETE /v1/contacts/lists và POST /v1/contacts/lists/batch hoạt động trên tài khoản sở hữu khóa. Việc tạo, chỉnh sửa và xóa chính các danh sách (/v1/lists) có yêu cầu sub_account_id.
• Webhook tin nhắn đến — các endpoint mà hệ thống bên ngoài đăng vào được gắn với tài khoản có thông tin xác thực đã 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.

Liệt kê các tài khoản phụ của bạn, hoặc kiểm tra một email #

GET /v1/subaccounts

Khi được gọi mà không có tham số, nó sẽ trả về mọi tài khoản phụ thuộc đại lý của bạn trong một mảng data. Thêm tham số truy vấn tùy chọn email để tra cứu một khách hàng cụ thể:

curl "https://api.dmchamp.com/v1/[email protected]&apiKey=YOUR_API_KEY"

• Email đó thuộc về một trong các tài khoản phụ đang hoạt động của bạn → HTTP 200, chỉ với tài khoản đó: { "success": true, "data": { ... } }.
• Email đó không thuộc về tài khoản nào → HTTP 404, Agency Sub Account not found.

Không có tham số nào trả về câu trả lời có hoặc không đơn thuần, vì vậy hãy đọc mã trạng thái: 200 nghĩa là email đó là một trong những khách hàng của bạn, 404 nghĩa là không phải. Các tài khoản phụ đã xóa sẽ bị loại bỏ, vì vậy một tài khoản bạn đã xóa cũng sẽ hiển thị là 404.

Mỗi tài khoản được trả về cùng với hồ sơ, cài đặt, giới hạn sử dụng và các tính năng đã được bật, đây là tất cả những gì bạn cần để hiển thị một hàng khách hàng trong bảng điều khiển của riêng bạn.

Phản hồi không bao giờ chứa thông tin xác thực. Các khóa API, mật khẩu, mã thông báo đăng nhập và chi tiết về các kênh mà khách hàng đã kết nối (Twilio, Google, Meta và tự mang theo khóa riêng) sẽ bị xóa trước khi gửi đi. Không có tham số nào để chọn các trường bạn nhận lại, vì vậy hãy đọc các trường bạn cần và bỏ qua phần còn lại.

Yêu cầu quyền truy cập API và tài khoản đại lý.

Tạo tài khoản khách hàng #

POST /v1/subaccounts

Việc tạo tài khoản chỉ cần một lệnh gọi với email, tên và tên doanh nghiệp của khách hàng. Có một vài điều cần biết trước khi bạn xây dựng quy trình đăng ký dựa trên nó.

Bạn không thể chọn mật khẩu. Không có trường mật khẩu: mật khẩu sẽ được tạo cho bạn và trả về một lần duy nhất dưới dạng temporary_password trong phản hồi 201. Hãy lưu trữ hoặc chuyển nó đi ngay lập tức, vì sẽ không có cách nào để xem lại nó. Khách hàng có thể thay đổi mật khẩu từ hồ sơ của họ hoặc đặt lại từ màn hình đăng nhập.

curl -X POST "https://api.dmchamp.com/v1/subaccounts" \
  -H "X-API-Key: YOUR_AGENCY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "first_name": "Alex",
    "last_name": "Client",
    "business_name": "Client Co",
    "send_account_info_to_sub_account": true
  }'

Không có gì được gửi email cho khách hàng trừ khi bạn yêu cầu. Theo mặc định, tài khoản được tạo một cách âm thầm và việc thông báo cho khách hàng là công việc của bạn. Gửi send_account_info_to_sub_account: true và họ sẽ nhận được email chào mừng kèm theo địa chỉ email, mật khẩu tạm thời đó và liên kết để đăng nhập, tất cả đều trên tên miền white-label của riêng bạn và dưới thương hiệu của bạn.

Cờ này chỉ áp dụng cho email của khách hàng. Đại lý của bạn luôn nhận được thông báo Tài khoản phụ mới được tạo, nhưng thông báo này không bao giờ chứa mật khẩu: vì lý do bảo mật, phản hồi 201 là nơi duy nhất bạn nhận được mật khẩu đó. Nếu bị mất, khách hàng sẽ tự đặt mật khẩu mới bằng cách chọn Quên mật khẩu trên màn hình đăng nhập.

Bạn có thể tự thiết lập số tín dụng ban đầu. usage_limits.credits là hạn mức chi tiêu ban đầu của khách hàng và usage_limits.monthly_credits là khoản phụ cấp hàng tháng định kỳ. Gửi "credits": 0 và tài khoản sẽ bắt đầu với số dư bằng không; bỏ qua credits và tài khoản sẽ bắt đầu với số dư 100 tín dụng dùng một lần để AI có thể trả lời ngay lập tức. Không có tùy chọn nào trừ tiền từ quỹ đại lý của bạn khi tạo tài khoản: quỹ của bạn chỉ bị trừ khi khách hàng thực sự sử dụng tín dụng.

Tên doanh nghiệp phải là duy nhất trong đại lý của bạn. Hai khách hàng của bạn không thể cùng tên là “Client Co”, vì tên đó là thứ xác định tài khoản trên bảng điều khiển và các báo cáo của bạn. Tên của các đại lý khác không ảnh hưởng đến điều này.

Khi lệnh gọi thất bại:

Xóa tài khoản khách hàng #

DELETE /v1/[email protected] (hoặc ?uid=SUB_ACCOUNT_UID)

curl -X DELETE "https://api.dmchamp.com/v1/[email protected]" \
  -H "X-API-Key: YOUR_AGENCY_API_KEY"

Thao tác này giống như nút xóa trên trang Tài khoản phụ và không thể hoàn tác. Khách hàng sẽ bị khóa quyền truy cập ngay lập tức và không còn được tính vào tổng số khách hàng của bạn; các cuộc hội thoại, danh bạ, tác nhân và kênh kết nối của họ sẽ bị xóa trong nền trong vài phút tiếp theo. Gói dịch vụ mà khách hàng đã mua thông qua trang thanh toán của bạn sẽ bị hủy.

{
  "success": true,
  "message": "Sub-account deletion started",
  "data": { "uid": "SUB_ACCOUNT_UID", "email": "[email protected]", "status": "deletion_started" }
}

• Truyền email hoặc uid. Nếu bạn truyền cả hai, chúng phải cùng chỉ định một khách hàng.
• Chỉ có thể xóa khách hàng của riêng bạn. Bất kỳ email hoặc uid nào khác, hoặc khách hàng đã bị xóa, sẽ trả về 404.
• Gọi lại khi quá trình xóa vẫn đang chạy sẽ trả về 200 kèm theo "status": "already_in_progress".
• Các trợ lý AI được kết nối thông qua máy chủ MCP sẽ có công cụ này dưới dạng delete_subaccount khi kết nối với địa chỉ MCP tiêu chuẩn (các công cụ đại lý sẽ bị loại bỏ khỏi địa chỉ MCP nhãn trắng).
• Để tạm dừng khách hàng một thời gian mà không làm mất dữ liệu, hãy tạm dừng họ thay vì xóa: họ sẽ bị khóa quyền truy cập, mọi thứ được giữ nguyên và chỉ cần một lệnh gọi để khôi phục.

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 một tác nhân được đánh giá theo múi giờ của chính tài khoản phụ đó, vì vậy một 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 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 (Setup Wizard). Đối với các khách hàng được phục vụ trọn gói — nơi bạn xây dựng tác nhân AI 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. Thay vào đó, họ sẽ truy cập vào màn hình chính thông thường — bảng điều khiển trên máy tính, các cuộc trò chuyện trên điện thoại — 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": "[email protected]",
    "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": "[email protected]",
    "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, "Deals": false, "Automations": false },
      "settings_nav": { "team": false }
    }
  }'

Phản hồi

{
  "success": true,
  "data": {
    "subAccountUid": "SUB_ACCOUNT_UID",
    "menuVisibility": {
      "side_nav": { "Dashboard": false, "Deals": 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). Campaigns chỉ ẩn trang Chiến dịch đã ngừng hoạt động; các trang Tác nhân AI và Phát sóng không có khóa và không thể bị ẩn theo cách này. 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: 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.

Cùng một đối tượng menuVisibility đó cũng nhận hai trường tùy chọn cho bảng điều khiển chính của khách hàng. dashboard_widgets ánh xạ một id tiện ích con tới true (hiển thị) hoặc false (ẩn), và dashboard_order là danh sách các id tiện ích con theo thứ tự mà chúng sẽ xuất hiện. Các id, theo thứ tự mặc định của chúng, là kpis, performance, credits (Mức sử dụng tín dụng), funnel, inbox, outcomes, channel_health, ai_cost, ai_human, heatmap (Thời điểm hoạt động tích cực nhất), top_campaigns (Các đại lý hàng đầu), contacts_by_country, activity và tasks_deals. Các id bị thiếu vẫn sẽ hiển thị, và các id bị bỏ lại ngoài dashboard_order sẽ tuân theo thứ tự mặc định. Ví dụ: "dashboard_widgets": { "credits": false } sẽ ẩn bảng tín dụng khỏi khách hàng.

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"
    ]
  }'

Những đ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 tất cả các 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ự 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 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 Chat Widget, WhatsApp Web hoặc Instagram”.
• automations_edit, broadcasts_send và smart_lists_create cho phép khách hàng tạo, chỉnh sửa và xóa các tự động hóa, chương trình phát sóng và danh sách thông minh của riêng họ. Một danh sách không liệt kê cả ba mục này sẽ giữ nguyên trạng thái hiện tại của chúng (trên một tài khoản phụ mới: cả ba đều bật), vì vậy một tích hợp cũ vẫn tiếp tục hoạt động. Nếu bạn liệt kê ít nhất một mục, danh sách sẽ thiết lập cả ba: những mục bạn bỏ qua sẽ bị tắt. Khách hàng vẫn có thể sử dụng những gì bạn đã thiết lập cho họ theo bất kỳ cách nào, và khóa API đại lý của bạn cũng như các phiên làm việc của riêng bạn trong tài khoản của khách hàng không bao giờ bị hạn chế bởi ba mục này.
• Mọi tính năng khác đều chính xác như danh sách đã nêu, khi tạo và khi cập nhật. Một khách hàng được tạo hoặc cập nhật với danh sách features sẽ nhận được các tính năng đó và không có gì khác. Điều này bao gồm crm_erp_integrations (phần tích hợp CRM & ERP, nơi khách hàng kết nối Odoo): nó chỉ bật khi danh sách của bạn bao gồm nó, vì vậy hãy thêm nó nếu khách hàng cần kết nối CRM hoặc ERP. Một khách hàng được tạo mà không có bất kỳ danh sách features nào sẽ nhận được bộ mặc định, bao gồm cả tính năng này.
• 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ụ bằng 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 điểm cuối đó 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. Một creditManagementMode cấp cao nhất ("manual" hoặc "reselling") sẽ chuyển đổi chế độ tín dụng của khách hàng; một tài khoản phụ được tạo thông qua API sẽ bắt đầu ở chế độ thủ công, vì vậy hãy chuyển nó sang "reselling" trước khi khách hàng thanh toán qua quy trình thanh toán SaaS Mode của bạn (xem Tài khoản phụ, Chạy bản dùng thử miễn phí).

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 } chọn tham gia (hoặc hủy tham gia) gói Max AI cho khách hàng, 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ừ “0 tín dụng, thanh toán bằng 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à quyết định có chủ đích cho từng khách hàng thay vì là mặc định cho toàn bộ đại lý.

Để hạn chế các cấp độ (tiers) mà Tác nhân của khách hàng có thể chọn (thay vì chỉ giới hạ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ỳ gói nào. Một danh sách được thiết lập ở đây được tính là khóa thủ công: allowed_ai_tiers của gói (xem Quản lý các gói giá của bạn qua API) sẽ không còn ảnh hưởng đến khách hàng này khi gia hạn. Điều này quan trọng vì một tài khoản phụ tự chọn gói AI của riêng mình sẽ tiêu tốn 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ẽ áp dụng Mức giá Nội bộ (giảm 20% cho các hành động Max và Mini, khách hàng tiềm năng và tự động hóa của Lead Finder) cho một khách hàng thay vì áp dụng trên 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 }
      }
    }
  }'

Chỉ các danh mục bạn gửi mới thay đổi: mỗi danh mục sẽ được hợp nhất với cài đặt hiện tại của máy khách và mọi danh mục bạn bỏ qua sẽ giữ nguyên giá trị của nó. 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 khách hàng tạm dừng đă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 ngay lập tức — tin nhắn gửi đi, phát sóng, phản hồi AI trên mọi kênh — và khi họ đăng nhập, họ sẽ thấy khóa Tài khoản đã tạm dừng toàn màn hình (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 tác nhân, phát sóng, kênh đã kết nối, danh bạ và lịch sử trò chuyện đều giữ nguyên như cũ, 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, việc bỏ tạm dừng sẽ xóa trạng thái chặn được thiết lập 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 có tính 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 sẽ không tự động nhận được email — nhiều đại lý sử dụng nhãn trắ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ệ giữa bạn và 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 trên địa chỉ MCP tiêu chuẩn (các công cụ đại lý sẽ bị loại bỏ khỏi địa chỉ MCP nhãn trắng).

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.

Thử lại một cách an toàn. Hãy gửi cùng một khóa idempotency khi bạn thử lại một lệnh gọi, ví dụ như sau khi hết thời gian chờ, và các khoản tín dụng sẽ chỉ được thêm hoặc bớt một lần. Trong vòng 24 giờ, một lần lặp lại với cùng khóa và cùng chi tiết sẽ trả về kết quả đầu tiên (với tiêu đề Idempotent-Replayed: true) thay vì thay đổi số dư lần thứ hai. Cùng một khóa với email, số tiền hoặc mô tả khác sẽ bị từ chối (422), và một lần lặp lại đến trong khi lệnh gọi đầu tiên vẫn đang chạy sẽ nhận được mã 409: hãy đợi một chút và thử lại. Các lệnh gọi không có khóa vẫn hoạt động như trước.

cURL

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

Phản hồi

{
  "success": true,
  "data": {
    "email": "[email protected]",
    "previous_balance": 1200,
    "adjustment": 500,
    "new_balance": 1700
  }
}

Một giá trị amount âm khiến số dư xuống dưới 0 sẽ bị từ chối với 400, thông báo cho bạn số dư khả dụng và số tiền bạn đã cố gắng khấu trừ. Nếu khách hàng đang ở chế độ đại lý bán lại, số tiền được thêm vào sẽ được tính là tín dụng họ đã mua: nó được lấy từ quỹ tín dụng đại lý của bạn ngay tại thời điểm đó, giống hệt như giao dịch mua qua thanh toán của bạn, và nó vẫn tồn tại sau lần đặt lại hàng tháng tiếp theo của họ giống như một lần nạp tiền thực sự. Khi quỹ của bạn không đủ để chi trả số tiền đó, lệnh gọi sẽ bị từ chối với 402 và không có gì thay đổi, vì vậy hãy nạp tiền vào số dư đại lý của bạn trước. Việc khấu trừ đối với khách hàng đại lý bán lại chỉ xóa tín dụng khỏi khách hàng đó; không có gì được trả lại vào quỹ của bạn. Đối với khách hàng được phân bổ tiêu chuẩn, khoản thêm vào được coi là một phần trong hạn mức định kỳ của họ và không lấy gì từ quỹ của bạn cho đến khi khách hàng chi tiêu số đó. Dù bằng cách nào, chúng cũng là 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 tài khoản đó) sẽ không bao giờ cắt giảm chúng — chỉ có hạn mức định kỳ và tín dụng gói mới phải chịu các giới hạn đó.

Đọ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": "[email protected]",
        "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": "[email protected]",
    "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": "[email protected]",
        "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": "[email protected]",
        "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
  }
}

Mỗi hàng cũng chứa số lượng AI Agent của khách hàng (totalAgents, activeAgents, pausedAgents, draftAgents), và cấp cao nhất thêm totalActiveAgents và totalPausedAgents cho trang. Các trường chiến dịch chỉ bao gồm các chiến dịch cổ điển. hasIssues / issueDetails gắn cờ các tài khoản phụ cần xem xét. Trên một tài khoản có các agent, chúng đến từ điểm sẵn sàng của các agent đang bật (ví dụ: "WhatsApp Web is disconnected" hoặc "Agent \"Front desk\": Routed on a channel that is not connected"); các agent đang tắt sẽ không bao giờ bị gắn cờ. Trên một tài khoản không có agent, chúng gắn cờ các chiến dịch cổ điển, chẳng hạn như chiến dịch đã tạm dừng. Hãy sử dụng tính năng này để xây dựng bảng điều khiển kiểm tra sức khỏe trên toàn bộ danh mục thay vì phải mở từng khách hàng để xem agent nào đang bị tắt.

Để 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 đến.
• Tự động nạp tiền tài khoản phụ — cấp tín dụng cho tài khoản phụ thông qua webhook + API.
• API Tác nhân AI: tạo và cấu hình Tác nhân AI.
• API Chiến dịch: tài nguyên chiến dịch cổ điển đã lỗi thời, bao gồm tham chiếu trường đầy đủ.
• API Kết nối kênh — kết nối các kênh của khách hàng.
• API Điểm truy cập: quyết định Tác nhân nào sẽ tiếp nhận cuộc trò chuyện mới.
• Hướng dẫn API phân tích (trong phần API) — tổng hợp tài khoản phụ đại lý và mọi điểm cuối báo cáo khác.
• Ảnh chụp nhanh (Snapshots) — những gì ảnh chụp nhanh ghi lại và cách xây dựng nó trong bảng điều khiển.