API untuk Agensi #

Sebagai agensi, Anda dapat menggunakan REST API yang sama dengan yang digunakan klien Anda, tetapi arahkan permintaan individual ke salah satu sub-akun yang Anda kelola alih-alih ke akun Anda sendiri. Hal ini memungkinkan Anda membangun perangkat yang melakukan onboarding klien dari awal hingga akhir — membuat kampanye mereka, melatih AI mereka pada basis pengetahuan, mengimpor kontak mereka, menghubungkan saluran pesan mereka, dan membeli nomor telepon — semuanya tanpa harus masuk ke setiap sub-akun secara manual.

Halaman ini hanya mencakup perilaku khusus agensi: cara bertindak atas nama sub-akun dengan parameter sub_account_id. Untuk dasar-dasarnya (pembuatan kunci, autentikasi, URL dasar, format kesalahan, batas kecepatan), mulailah dengan panduan Akses API. Semua yang ada di sana juga berlaku di sini — Anda melakukan autentikasi dengan kunci API akun agensi Anda.

Cara kerja “bertindak atas nama” #

Secara default, setiap permintaan API bertindak pada akun yang memiliki kunci API tersebut — yaitu akun agensi Anda. Untuk bertindak pada akun klien yang dikelola, tambahkan parameter opsional sub_account_id ke dalam permintaan, yang diatur ke id akun klien tersebut.

• Hilangkan sub_account_id → permintaan bertindak pada akun agensi Anda sendiri.
• Sertakan sub_account_id → permintaan bertindak pada sub-akun tersebut, tetapi hanya setelah platform mengonfirmasi bahwa sub-akun tersebut benar-benar milik Anda.

Anda selalu melakukan autentikasi dengan kunci API akun agensi Anda. Anda tidak perlu kunci milik sub-akun tersebut, dan Anda tidak perlu menangani kredensial sub-akun.

Tempat meletakkannya #

• Endpoint GET / DELETE → teruskan sebagai parameter kueri: ?sub_account_id=THE_SUB_ACCOUNT_ID (bersama dengan apiKey Anda, jika Anda melakukan autentikasi melalui kueri).
• Endpoint POST / PUT / PATCH → sertakan dalam JSON request body sebagai "sub_account_id": "THE_SUB_ACCOUNT_ID".
• Asisten AI → tidak ada yang perlu dikonfigurasi. Server MCP membawa pengaturan yang sama pada alat baca (read tools)-nya, sehingga satu koneksi dengan kunci agensi Anda dapat melaporkan setiap klien: cukup sebutkan nama klien dalam permintaan Anda (“berapa banyak kontak yang dimiliki Bella’s Bistro?”). Tindakan tulis (write actions) juga tersedia: setiap endpoint yang menerima sub_account_id diekspos sebagai alat, sehingga Anda dapat membuat, mengubah, dan mengirim atas nama klien dari koneksi yang sama.

Menemukan id sub-akun #

sub_account_id adalah id unik akun klien. Anda bisa mendapatkan daftar sub-akun Anda beserta id-nya dari titik akhir API SubAccounts (lihat panduan Sub-Accounts) atau dari halaman Sub Accounts di bilah sisi.

Kepemilikan selalu diverifikasi #

Saat Anda meneruskan sub_account_id, platform akan memeriksa apakah akun tersebut adalah sub-akun yang valid dan apakah akun tersebut milik agensi Anda. Hanya setelah itu permintaan akan diproses.

Jika id tidak diketahui, bukan merupakan sub-akun, atau milik agensi lain, permintaan akan gagal dengan respons 404:

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

Mengapa 404 dan bukan 403? Respons “forbidden” (terlarang) akan memberi tahu pihak luar bahwa id tersebut ada tetapi bukan milik mereka. Mengembalikan 404 yang sama untuk “tidak ada” dan “bukan milik Anda” berarti endpoint tersebut tidak dapat digunakan untuk mengetahui id akun mana yang dimiliki oleh agensi lain. Anggap 404 di sini sebagai “ini bukan sub-akun yang Anda kelola.”

Di mana sub_account_id didukung #

sub_account_id diterima di hampir setiap endpoint sumber daya — panggilan apa pun yang membuat, membaca, memperbarui, atau menghapus data akun itu sendiri. Dalam praktiknya, Anda dapat menyediakan dan menjalankan seluruh pengaturan sub-akun dengan kunci agensi Anda:

• Pengaturan AI — kampanye, agen, FAQ, sumber basis pengetahuan (perayapan situs web dan unggah dokumen), grup basis pengetahuan, siaran, fungsi kustom, server MCP
• Kontak & CRM — kontak (termasuk impor), daftar, tag, tugas, kesepakatan, janji temu, acara
• Saluran & nomor — hubungkan WhatsApp / WhatsApp Web / Telegram / Instagram & Messenger / LINE, cari / beli / kelola nomor telepon, templat WhatsApp, perutean saluran
• Pesan & konten — kirim pesan, sesi obrolan, ekspor obrolan, ringkasan harian
• Pengaturan & integrasi — webhook, konfigurasi widget obrolan, konfigurasi white-label, SMS BYOK dan pengaturan akun lainnya, analitik

Pada setiap parameter ini bersifat opsional — abaikan parameter tersebut dan panggilan akan bertindak atas akun agensi Anda sendiri, sehingga satu integrasi dapat melayani keduanya. Kredit dan penggunaan selalu berasal dari akun yang Anda targetkan: biaya untuk kampanye, pesan, tag, dan nomor sub-akun akan memotong saldo sub-akun tersebut.

Di mana hal ini TIDAK berlaku #

Beberapa endpoint bersifat tingkat agensi atau ditujukan untuk diri sendiri dan mengabaikan sub_account_id:

• Mengelola sub-akun itu sendiri — endpoint SubAccounts (membuat / mencantumkan / memperbarui sub-akun) dan endpoint batas pengeluaran BYOK sudah menyebutkan sub-akun di jalur URL mereka sendiri. Endpoint harga dan kebijakan serta endpoint pemantauan obrolan mengikuti pola yang sama.
• Menyalin Agen antar akun — POST /v1/subaccounts/agents/copy menyebutkan kedua akun itu sendiri, dengan mengambil tujuan sebagai targetUserId. Lihat contoh pengerjaan di bawah. (POST /v1/subaccounts/campaigns/copy yang lebih lama bekerja dengan cara yang sama tetapi sudah tidak digunakan lagi bersama dengan API Kampanye lainnya.)
• Menyesuaikan kredit, dan dua rollup seluruh agensi — POST /v1/subaccounts/credits mengidentifikasi sub-akun berdasarkan email sebagai gantinya; GET /v1/subaccounts/credit-usage dan GET /v1/subaccounts/campaign-status melaporkan setiap sub-akun sekaligus, jadi tidak ada satu akun pun yang menjadi target.
• Akun agensi Anda sendiri — Manajemen kunci API, pelaporan penggunaan agensi, manajemen tim, dan tingkat harga Anda selalu bertindak pada akun agensi Anda.
• Webhook pesan masuk — endpoint tempat sistem eksternal mengirimkan data ke dalam terikat pada akun yang kredensialnya mengonfigurasinya, jadi tidak ada yang perlu dialihkan.

Daftar parameter yang diterima oleh setiap titik akhir yang selalu terkini dan dapat dibaca mesin tersedia di referensi API dasbor Anda (Settings → Integrations → API Key) dan spesifikasi OpenAPI di GET /v1/docs/openapi.yaml. Kami sering merilis perubahan API — jadikan itu sebagai sumber kebenaran.

Contoh pengerjaan: menghubungkan Instagram & Messenger untuk sub-akun #

Menghubungkan Instagram & Messenger adalah alur berbasis browser. Anda memulainya dengan API, memberikan URL persetujuan yang dikembalikan kepada klien (atau membukanya untuk mereka), menunggu mereka memberikan otorisasi di browser mereka, lalu memilih halaman mana yang akan dihubungkan — semuanya sambil menargetkan sub-akun mereka dengan sub_account_id.

Langkah 1 — Memulai koneksi #

Panggil endpoint connect dengan sub_account_id klien di dalam body. Tidak ada kredensial yang dikirim di sini; platform mengembalikan URL persetujuan yang harus dibuka klien di browser, ditambah token korelasi satu kali pakai.

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

Respons:

{
  "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"
}

Arahkan klien ke oauth_url di browser untuk melakukan otorisasi. state_token mengorelasikan upaya ini dan merupakan rahasia yang berumur pendek — jangan mencatatnya. Upaya ini kedaluwarsa pada expires_at; jika sudah lewat, mulailah lagi.

Langkah 2 — Lakukan polling hingga halaman dimuat #

Setelah klien memberikan otorisasi, lakukan polling pada endpoint status (dengan sub_account_id yang sama, kali ini sebagai parameter kueri) hingga halaman yang dapat dihubungkan muncul.

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

Respons:

{
  "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
}

Kolom status bergerak melalui pending → token_received → pages_loaded → connected. Tunggu pages_loaded sebelum memilih halaman. Dua status kesalahan terminal juga dapat muncul alih-alih melanjutkan: failed dan expired (klien menolak persetujuan, atau jendela ~30 menit token status telah berakhir) — kolom reason disertakan saat salah satunya terjadi. Berhenti melakukan polling dan mulai ulang di Langkah 1 jika Anda melihatnya; jangan menunggu pending selamanya. Token akses halaman tidak pernah dikembalikan.

Langkah 3 — Pilih halaman untuk dihubungkan #

Pilih salah satu id halaman dari Langkah 2 dan pilih halaman tersebut. Memilih halaman akan menghubungkan Instagram dan Messenger untuk halaman tersebut. Sertakan sub_account_id di dalam body lagi.

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()

Respons:

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

Selesai — Instagram dan Messenger kini telah terhubung pada sub-akun klien. Anda hanya perlu memberikan page_id; kredensial yang mendasarinya diselesaikan di server dan tidak pernah diteruskan melalui integrasi Anda.

Contoh pengerjaan: membeli nomor untuk sub-akun #

Membeli nomor bekerja dengan cara yang sama: cari dengan sub_account_id di dalam kueri, lalu beli dengan menyertakannya di dalam body. Kredit akan dipotong dari saldo sub-akun, dan nomor tersebut akan disediakan pada sub-akun tersebut.

Pencarian (cURL):

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

Pembelian (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();

Pembelian (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()

Respons:

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

Nomor tersebut disediakan dalam status PURCHASED dan pendaftaran pengirim WhatsApp berlanjut di latar belakang. Lakukan polling GET /v1/phone-numbers/{phoneNumber}/status?sub_account_id=abc123def456 hingga status mencapai ONLINE sebelum mengirim.

Contoh pengerjaan: mengirim Agen templat ke setiap klien baru #

Pola agensi yang biasa dilakukan adalah menyimpan satu Agen utama di akun agensi Anda, yang disetel sesuai keinginan Anda agar setiap klien dapat memulai, dan mencetak salinannya ke setiap sub-akun baru pada saat penyediaan. Itu adalah tiga panggilan, dan tidak ada yang perlu diulang setelahnya: salinan tersebut menyimpan pengaturannya sampai Anda mengubahnya.

Langkah 1 — Salin Agen masuk #

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

Respons tersebut membawa id Agen baru di data.agent_id. FAQ, basis pengetahuan, dan pustaka media ikut serta; templat WhatsApp, kiriman sosial yang terhubung, dan kontak akun sumber sengaja tidak disertakan. Daftar bidang lengkap ada di API Agen AI.

Perhatikan bahwa endpoint ini menggunakan targetUserId alih-alih sub_account_id — endpoint ini menyebutkan kedua akun itu sendiri. Dua panggilan di bawah ini menggunakan parameter sub_account_id yang normal.

Langkah 2 — Aktifkan #

Salinan selalu tiba dalam keadaan dijeda, sehingga tidak dapat mengirim pesan kepada siapa pun sampai Anda mengizinkannya. Ini juga saat yang tepat untuk menyematkan tingkat AI yang Anda inginkan untuk klien tersebut; tingkat tersebut akan tetap di sana, jadi tidak perlu menerapkannya kembali sesuai jadwal.

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

Untuk mencegah klien mengubah tingkat setelahnya, kunci tingkat yang diizinkan pada sub-akun alih-alih mengirim ulang nilainya.

Langkah 3 — Arahkan saluran klien ke kampanye tersebut #

Salinan juga tiba tanpa perutean, jadi tidak ada yang mencapainya sampai Anda menjadikannya penjawab di saluran yang telah dihubungkan oleh klien. Satu panggilan per saluran:

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

Dari sini, pesan pertama kali dari kontak yang tidak dikenal di saluran tersebut akan diambil oleh Agen yang disalin secara otomatis. Lihat Arahkan saluran ke Agen untuk saluran lain dan perutean per nomor.

Tetapkan zona waktu klien saat Anda membuat sub-akun. Teruskan time_zone_id pada POST /v1/subaccounts. Jam aktif kampanye dievaluasi dalam zona waktu sub-akun itu sendiri, sehingga klien yang dibuat tanpa zona waktu akan memiliki jadwal yang dibaca berdasarkan UTC — yang secara diam-diam mengubah waktu kapan asisten diizinkan untuk membalas.

Lewati panduan penyiapan untuk klien yang Anda konfigurasi sendiri #

POST /v1/subaccounts

Secara default, saat pemilik sub-akun baru masuk untuk pertama kalinya, mereka akan dipandu melalui Panduan Penyiapan. Untuk klien yang layanannya dikerjakan untuk mereka — di mana Anda membuat kampanye dan menghubungkan saluran sebelum klien masuk — berikan guided_onboarding: false saat Anda membuat akun. Mereka akan langsung diarahkan ke dasbor, dan entri Panduan Penyiapan akan disembunyikan dari bilah sisi mereka.

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

Abaikan kolom tersebut (atau kirim true) dan wizard akan berperilaku persis seperti biasanya, sehingga integrasi yang sudah ada tidak perlu diubah. Untuk mengembalikan wizard kepada klien nanti, tampilkan kembali item guided_onboarding dengan PUT /v1/subaccounts/{subAccountUid}/menu-visibility (di bawah) — visibilitas menu mengontrol apakah wizard dapat diakses, guided_onboarding hanya mengontrol pengalihan saat pertama kali masuk.

Nonaktifkan Tugas, Ringkasan Harian, atau Pustaka Media untuk klien #

POST /v1/subaccounts

Ketiga fitur ini aktif untuk setiap klien baru kecuali Anda menentukan sebaliknya, dan fitur-fitur tersebut berperilaku berbeda dari fitur lain dalam panduan ini: fitur ini bersifat opt-out (bisa dinonaktifkan), bukan opt-in. Tidak menyertakannya dalam features saja tidak cukup, karena daftar features integrasi lama tidak pernah menyebutkannya — kami tidak dapat membedakan antara “agensi mematikan ini” dengan “daftar ini ditulis sebelum opsi tersebut ada”.

Jadi, nyatakan secara langsung dengan 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
    }
  }'

Setiap kunci bersifat opsional; apa pun yang Anda abaikan akan tetap aktif. Dengan tasks: false, AI berhenti membuat tugas untuk klien tersebut dan tidak ada email “Tugas Baru Dibuat” yang dikirim; dengan daily_summaries: false, ringkasan malam hari tidak akan pernah dibuat atau dikirim melalui email.

feature_settings adalah satu-satunya hal yang mematikan ketiga fitur ini saat pembuatan. Tidak menyertakannya dalam features tidak akan berpengaruh apa pun, tidak peduli bagaimana tampilan daftar Anda yang lain — itu disengaja, agar integrasi lama tidak kehilangan ketiganya secara diam-diam.

Untuk mengubah hal ini setelahnya, kirim daftar features lengkap ke PUT /v1/subaccounts/{subAccountUid}/features — di sana, keberadaan dalam daftar akan mengaktifkan fitur dan ketidakhadirannya akan menonaktifkannya.

Masuk otomatis klien Anda ke sub-akun mereka (SSO) #

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

Satu panggilan dengan kunci API agensi Anda akan mengembalikan URL siap pakai yang langsung memasukkan klien ke sub-akun mereka sendiri — tanpa layar masuk, tanpa langkah kata sandi, tidak ada yang perlu dibangun di atasnya. Buka di tab baru, pengalihan, atau iframe di dalam produk Anda sendiri.

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

Respons

{
  "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"
}

Cara menggunakannya dengan baik:

• Satu lompatan. Membuka url akan memasukkan klien dan langsung mengarahkan mereka ke halaman redirect di dasbor — tanpa layar masuk, tanpa halaman perantara. deep_link_url menyebutkan tujuan yang sama, bagi integrator yang lebih memilih menavigasi bingkai secara eksplisit setelah masuk; setelah sesi ada, jalur dasbor mana pun akan berfungsi dalam konteks peramban tersebut.
• Buat sesuai permintaan, buka segera. Tautan tersebut berisi kredensial masuk dan kedaluwarsa setelah sekitar satu jam. Minta tautan tersebut di sisi server pada saat klien mengeklik, dan jangan pernah menyimpan atau mengirimkannya melalui email.
• Token masuk dikirim dalam fragmen URL (#…), yang tidak pernah dikirim oleh peramban ke server, dan token tersebut dihapus dari bilah alamat segera setelah digunakan.
• Hanya sub-akun Anda sendiri. Titik akhir akan menolak akun apa pun yang tidak dimiliki oleh agensi Anda.
• Tautan yang kedaluwarsa akan menampilkan kesalahan yang jelas dengan jalur coba lagi — buatlah yang baru.

Sembunyikan item navigasi pada sub-akun #

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

Mengontrol item bilah sisi dan pengaturan mana yang dilihat oleh sub-akun — berguna saat Anda menyematkan dasbor dan hanya menginginkan antarmuka yang belum dicakup oleh produk Anda. Apa pun yang tidak tercantum akan tetap terlihat; kirim null sebagai seluruh nilai menuVisibility untuk mengatur ulang semuanya agar terlihat. Menyembunyikan item akan menyembunyikan entri menu — pasangkan dengan fitur yang Anda berikan kepada sub-akun untuk pembatasan ketat.

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

Respons

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

side_nav menerima 13 kunci ini, yang cocok dengan nama item bilah sisi: Dashboard, DailySummaries, Chats, Contacts, Deals, Tasks, Automations, Campaigns, Appointments, Settings, Help, CreditsCounter (saldo kredit yang ditampilkan di bilah sisi) dan guided_onboarding (Panduan Penyiapan). Tiga kunci lainnya — AiInsights, Sub Accounts, dan Agency Reselling — diterima tetapi tidak melakukan apa pun: kunci tersebut hanya pernah diterapkan pada dasbor klasik yang sudah tidak digunakan lagi, jadi mengaturnya tidak akan berpengaruh pada sub-akun Anda. Kunci yang hilang berarti terlihat; saat Anda masuk ke sub-akun sendiri, item yang disembunyikan akan ditampilkan sementara agar Anda selalu dapat mengubahnya kembali.

Menyembunyikan halaman dari menu tidak pernah memberikan akses ke halaman tersebut. Automations memerlukan fitur automations yang diberikan pada sub-akun — atur kunci ke true tanpanya dan halaman tersebut tetap tidak akan muncul. Tasks dan DailySummaries bekerja sebaliknya: fitur tersebut aktif untuk setiap klien kecuali Anda mematikannya (lihat Nonaktifkan Tugas, Ringkasan Harian, atau Pustaka Media untuk klien).

Pilih jenis saluran mana yang dapat dihubungkan oleh klien #

PUT /v1/subaccounts/{subAccountUid}/features

Tombol Jenis Saluran yang Anda lihat pada tingkat paket adalah ID fitur biasa, jadi Anda dapat mengaturnya per klien dari API alih-alih dari dasbor. Ini adalah salah satu endpoint yang menamai sub-akun di URL-nya sendiri, sehingga tidak memerlukan 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"
    ]
  }'

Tiga hal yang perlu diperhatikan:

• Panggilan ini menggantikan seluruh daftar fitur. Kirimkan setiap fitur yang harus dipertahankan klien, bukan hanya fitur yang Anda ubah. ID yang sama berfungsi sebagai features pada POST /v1/subaccounts saat Anda membuat akun.
• Jenis saluran dan jumlah saluran adalah gerbang yang terpisah, dan keduanya berlaku. channels_1 / channels_3 / channels_unlimited mengontrol berapa banyak koneksi; ID channel_* mengontrol jenis mana saja. Contoh di atas berarti “maksimal 3 koneksi, dan hanya Widget Obrolan, WhatsApp Web, atau Instagram”.
• Tidak mengirim ID channel_* sama sekali berarti tidak ada pembatasan saluran. Itu adalah perilaku aslinya, itulah sebabnya klien yang ada tidak terpengaruh saat fitur ini dirilis. Kirim satu atau lebih dan semua yang lain akan muncul sebagai terkunci di halaman Saluran klien dengan catatan peningkatan alih-alih tombol Hubungkan. Saluran yang sudah dihubungkan klien akan tetap berfungsi.

Mengatur daftar saluran pada tingkat paket, sehingga setiap klien yang membeli tingkat tersebut akan mewarisinya, dilakukan di dasbor di bawah pengaturan paket agensi Anda. Endpoint ini mengaturnya pada satu sub-akun tertentu.

Tetapkan batas anggota tim yang tepat untuk klien #

PUT /v1/subaccounts/{subAccountUid}/limits

Fitur team_seats_* hanya menawarkan langkah tangga prasetel (3 / 5 / 10 / tidak terbatas). Untuk memberikan jumlah kursi tim yang tepat kepada klien — 2, 7, 15, atau berapa pun — tetapkan usage_limits.team_seats_limit sebagai gantinya. Nilai ini mengalahkan prasetel, dan platform akan memberlakukannya pada setiap undangan, penambahan langsung, dan penerimaan undangan: setelah batas tercapai, undangan lebih lanjut akan ditolak di sisi server.

• Bilangan bulat positif adalah batas yang tepat.
• 0 berarti anggota tim tidak disertakan — klien tidak dapat mengundang siapa pun.
• -1 berarti tidak terbatas.
• null menghapus batas kustom dan kembali ke prasetel team_seats_* mana pun yang ada di daftar fitur.

Menurunkan batas tidak akan pernah menghapus anggota tim yang sudah ada; ini hanya menghentikan penambahan anggota baru.

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

Anda juga dapat mengaturnya pada saat pembuatan: POST /v1/subaccounts menerima usage_limits.team_seats_limit dengan semantik yang sama. Untuk membaca nilai saat ini, ambil sub-akun dengan GET /v1/subaccounts?email=... dan lihat usage_limits.team_seats_limit (tidak ada/null = preset yang menentukan). Endpoint yang sama juga memperbarui credits, monthly_credits, roll_over_to_next_month, rollover_cap_months, rollover_expiry_days dan byok_monthly_limit_usd — kirim hanya kunci yang ingin Anda ubah.

Bagaimana hal ini berinteraksi dengan batas kursi paket SaaS. Paket SaaS Anda dapat memiliki alokasi kursinya sendiri (diatur dalam editor paket — lihat Kursi tim pada paket), yang diterapkan secara otomatis saat klien berlangganan. Batas yang Anda tetapkan melalui endpoint ini dihitung sebagai pemberian manual: membeli paket akan menggantinya dengan alokasi kursi paket tersebut (pembelian itu adalah pilihan paket yang eksplisit), namun pembaruan bulanan otomatis tidak akan pernah menimpa batas manual — sehingga pengecualian satu kali yang Anda berikan kepada klien akan tetap berlaku selama siklus penagihan mereka. Menghapus batas manual dengan null akan mengembalikan kendali bidang tersebut ke paket pada pembaruan berikutnya.

Batasi apa yang dibawa klien di antara pembaruan. Dua kunci usage_limits lainnya berada di samping roll_over_to_next_month. Keduanya juga diterima oleh POST /v1/subaccounts pada saat pembuatan, dan null menghapus salah satunya.

Jika tidak diatur, keduanya akan kembali ke paket klien; nilai yang dikirim di sini akan mengalahkan nilai paket. Hanya kredit berulang (tunjangan bulanan dan kredit paket) yang tunduk pada aturan ini: top-up, isi ulang otomatis, dan penambahan satu kali tidak pernah dibatasi atau kedaluwarsa. Setiap pemangkasan ditulis ke riwayat kredit klien sebagai Penyesuaian Kredit Batas Rollover atau Penyesuaian Kredit Kredit Kedaluwarsa dan tidak pernah dihitung sebagai penggunaan. Ekuivalen tingkat paket adalah rollover_cap_months dan rollover_expiry_days pada tingkat harga — lihat Bidang pada tingkat dan Membatasi apa yang di-rollover.

Tetapkan harga dan kebijakan AI per klien #

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

Delapan sakelar per-klien lainnya, di samping /limits, /features dan /menu-visibility di atas. Masing-masing mengambil uid sub-akun di URL (tidak ada parameter bodi/kueri sub_account_id — target sudah dinamai di jalur) dan dicakup dengan cara yang sama: kunci agensi Anda, dan sub-akun harus milik agensi Anda.

Model AI mana yang dapat digunakan klien

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 } memilih klien untuk masuk (atau keluar) dari tingkat Max AI — infrastruktur kami dengan harga daftar platform. Mengaktifkan ini untuk klien BYOK mengubah biaya AI mereka dari “gratis dengan kunci saya sendiri” menjadi “dibebankan ke kumpulan kredit saya”, jadi ini adalah keputusan per klien yang disengaja, bukan default seluruh agensi.

Untuk membatasi tingkat MANA yang boleh dipilih oleh kampanye dan Agen klien (daripada hanya membatasi Max), gunakan 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 adalah array yang diambil dari standard, economy, max, mini — ini MENGGANTIKAN daftar izin klien. Kirim null (atau []) untuk menghapus batasan dan membiarkan mereka memilih tingkat apa pun. Ini penting karena sub-akun yang memilih tingkat AI-nya sendiri akan membelanjakan dari kumpulan kredit Anda, jadi ini adalah tuas untuk menentukan model mana yang boleh dijalankan oleh klien reseller yang akan menambah tagihan Anda.

Balasan tertahan saat klien kehabisan kredit

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

Ketika saldo klien (atau kumpulan Anda) kosong, AI tidak dapat menjawab dan kontak tidak mendengar apa pun. Dengan enabled: true, setiap kontak yang menulis selama pemadaman akan mendapatkan message satu kali (maks 500 karakter, dikirim apa adanya di setiap saluran), dan AI akan menjawab percakapan tersebut secara nyata setelah kredit kembali. enabled: false menyimpan teks yang disimpan untuk nanti; enabled: false tanpa message menghapus pengaturan tersebut. Sakelar yang sama dengan Balasan tertahan saat kehabisan kredit di modal Edit sub-akun — lihat Balasan tertahan saat klien kehabisan kredit.

Berapa yang dibayarkan klien per tindakan AI, dan markup biaya WhatsApp

Dua cara untuk menetapkan tarif yang dihadapi klien Anda, dari yang paling sederhana hingga yang paling terperinci:

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 adalah harga dalam kredit yang dibakar oleh saldo SENDIRI sub-akun per tindakan AI model Max — markup yang dihadapi klien Anda di atas apa yang sebenarnya dibayar oleh kumpulan Anda. null menghapus penggantian (override) kembali ke harga daftar platform. Tarif harus setidaknya sebesar biaya tindakan Max untuk kumpulan Anda sendiri (sehingga Anda tidak akan pernah bisa menetapkan harga klien di bawah biaya Anda) dan tidak lebih dari 10 kredit; permintaan di luar jendela tersebut akan ditolak dengan batas bawah yang dihitung dalam pesan kesalahan.

Untuk harga per jenis tindakan alih-alih satu tarif Max tetap, gunakan 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 adalah GABUNGAN ke peta klien yang ada — kunci yang tidak Anda sebutkan dibiarkan seperti semula, dan null membatalkan kunci tersebut kembali ke default-nya. Kunci yang dikenali:

Tarif per-tindakan harus berupa angka lebih besar dari 0 hingga 10; wa_carrier_multiplier harus setidaknya 1 (tidak ada diskon di bawah biaya) hingga 10. Mengirim kunci yang tidak dikenal, atau nilai di luar rentang, akan menolak SELURUH permintaan dan menyebutkan setiap kunci yang bermasalah, sehingga kesalahan ketik tidak akan pernah secara diam-diam menyimpan harga yang sebenarnya tidak diterapkan.

Jika Anda adalah anggota Champions Circle, insider-rate meneruskan tarif diskon 20% Max/Lead Finder Anda ke satu klien alih-alih menerapkannya ke seluruh agensi:

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

Mengaktifkannya mengharuskan akun agensi Anda sendiri memiliki keanggotaan Circle; menonaktifkannya tidak pernah mengharuskan hal tersebut, sehingga anggota yang keanggotaannya telah kedaluwarsa selalu dapat menurunkan kembali tarif klien.

Kunci bagian dari playbook klien

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 adalah array yang diambil dari instructions, goal, rules, personality, conclude_unless — ini MENGGANTIKAN daftar terkunci klien. Bagian yang terkunci akan ditolak di sisi server jika SUB-AKUN itu sendiri mencoba mengubahnya (secara langsung, atau melalui kunci API), sementara Anda (melalui sub_account_id) dan tampilan admin dasbor klien sendiri masih dapat mengedit apa pun. Kirim null (atau []) untuk membuka kunci semuanya. Berguna untuk klien yang layanannya dikelola penuh oleh Anda (done-for-you) di mana Anda memiliki playbook dan dinilai berdasarkan hasilnya.

Atur preferensi notifikasi klien atas nama mereka

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 menggantikan seluruh set preferensi notifikasi klien (bukan penggabungan per-kunci — kirim setiap kategori yang ingin Anda pertahankan, sesuai dengan cara halaman Pengaturan sub-akun menyimpannya). Setiap kategori di bawah settings menerima enabled (boolean) dan hingga tiga channels dari email, in_app, webhook. Kirim null untuk mengatur ulang ke default platform.

Ketujuh endpoint merespons { "success": true, "data": { "subAccountUid": "...", ...the field(s) you set... } }, dan dicatat dalam log audit dengan nilai sebelum/sesudah. Kesalahan umum: 403 jika akun Anda bukan Agensi/Dev atau sub-akun bukan milik Anda untuk dikelola, 400 jika itu bukan sub-akun agensi atau nilai berada di luar rentang.

Menangguhkan klien yang telah menghentikan langganan mereka #

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

Ketika klien menangguhkan langganan mereka dengan Anda, jeda akun mereka alih-alih menghapusnya: semua yang mereka kirim akan langsung berhenti — pesan keluar, siaran, balasan AI di setiap saluran — dan saat mereka masuk, mereka akan melihat kunci layar penuh Akun dijeda (dengan pesan opsional dari Anda) alih-alih aplikasi. Tidak ada yang dihapus atau diputuskan: agen, kampanye, saluran yang terhubung, kontak, dan riwayat obrolan semuanya tetap seperti apa adanya, sehingga membatalkan jeda akan mengembalikan klien tepat di tempat mereka berhenti — tidak perlu melakukan pengaturan ulang.

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

Respons

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

Saat klien kembali, POST /v1/subaccounts/SUB_ACCOUNT_UID/unpause (tanpa isi) akan membuka kunci — pengiriman dan balasan AI akan segera dilanjutkan.

Perlu diketahui:

• Ini adalah status yang sama dengan tombol Hard blocked di dasbor (Memblokir / Menjeda Sub-Akun) — klien yang dijeda melalui API akan muncul sebagai diblokir di dasbor dan sebaliknya, dan membatalkan jeda akan menghapus blokir yang ditempatkan dari sisi mana pun. Status saat ini dapat dibaca dari bidang agency_block pada GET /v1/subaccounts (level dari "none", "soft_blocked" atau "hard_blocked").
• Kedua panggilan bersifat idempoten. Menjeda klien yang sudah dijeda hanya akan menyegarkan menyegarkan pesan, alasan, dan stempel waktu; membatalkan jeda klien yang aktif tidak mengubah apa pun.
• Klien tidak dikirimi email secara otomatis — banyak agensi menggunakan label putih (white-label), jadi memberi tahu klien diserahkan kepada Anda.
• Penagihan DM Champ Anda sendiri tidak terpengaruh. Menjeda klien hanya memengaruhi hubungan Anda dengan mereka.
• Asisten AI juga dapat melakukan ini: server MCP mengekspos titik akhir ini sebagai alat pause_subaccount dan unpause_subaccount.

Berikan atau kurangi kredit secara langsung #

POST /v1/subaccounts/credits

Menambah atau menghapus jumlah kredit yang tepat dari saldo satu sub-akun — ekuivalen API dari penyesuaian kredit manual dasbor. Ini adalah perubahan saldo satu kali, berbeda dari pengaturan monthly_credits, roll_over_to_next_month, rollover_cap_months dan rollover_expiry_days yang berulang pada PUT /v1/subaccounts/{subAccountUid}/limits.

Ini adalah satu-satunya endpoint di halaman ini yang mengidentifikasi sub-akun berdasarkan email alih-alih 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" }'

Respons

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

amount negatif yang akan membuat saldo di bawah nol akan ditolak dengan 400, memberi tahu Anda saldo yang tersedia dan jumlah yang Anda coba kurangi. Jika klien menggunakan penagihan Stripe mereka sendiri (mode pengecer), jumlah yang ditambahkan juga dihitung sebagai kredit yang mereka beli, sehingga tetap ada setelah reset bulanan berikutnya seperti halnya top-up nyata; pada klien alokasi standar, itu dianggap sebagai bagian dari tunjangan berulang mereka. Bagaimanapun, itu adalah penambahan satu kali, jadi batas rollover atau kedaluwarsa yang ditetapkan pada akun (atau paketnya) tidak akan pernah memangkasnya — hanya tunjangan berulang dan kredit paket yang tunduk pada aturan tersebut.

Membaca percakapan sub-akun #

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

Memungkinkan Anda membangun tampilan pemantauan atau dukungan untuk percakapan klien tanpa harus masuk ke akun mereka. Pertama, buat daftar kontak mereka dengan pratinjau pesan terbaru, lalu baca riwayat pesan lengkap satu kontak.

Daftar kontak

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

Respons

{
  "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"
  }
}

Kontak diurutkan berdasarkan aktivitas terbaru terlebih dahulu. Terus lakukan penomoran halaman dengan lastActivityAt selama hasMore adalah true.

Membaca pesan satu kontak

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

Respons

{
  "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"
  }
}

Pesan dikembalikan mulai dari yang terbaru; buka riwayat ke belakang dengan beforeTimestamp.

Membaca penggunaan kredit dan kesehatan kampanye di seluruh akun Anda #

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

Dua ringkasan gaya dasbor untuk setiap sub-akun yang Anda kelola, untuk membangun pelaporan agensi Anda sendiri alih-alih mengeklik setiap klien satu per satu.

Penggunaan kredit

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
  }
}

Masukkan subAccountId dan respons yang sama juga akan membawa records: biaya individu dengan amount, reason, campaignName, contactName dan timestamp. Klien yang menggunakan kunci BYOK mereka sendiri alih-alih kredit Anda akan memiliki angka biaya/token yang disembunyikan (costsRedacted: true) — itu adalah telemetri biaya platform, bukan sesuatu yang perlu ditampilkan kepada penampil pengecer.

Status kampanye

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
  }
}

hasIssues / issueDetails menandai sub-akun yang perlu diperhatikan — misalnya, kampanye yang dijeda, atau kampanye yang tidak memiliki saluran yang diarahkan kepadanya. Gunakan ini untuk membangun dasbor pemeriksaan kesehatan di seluruh portofolio alih-alih membuka setiap klien untuk melihat kampanye yang terhenti.

Untuk aktivitas pesan dan kredit deret waktu di seluruh klien (deret yang siap untuk grafik, bukan snapshot titik waktu), lihat GET /analytics/agency-rollup di panduan API Analitik.

Kirim akun klien yang sudah disiapkan #

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

Snapshot adalah templat yang dapat digunakan kembali: satu atau beberapa agen AI beserta basis pengetahuan, alat, dan media mereka, yang diambil dari akun Anda sendiri. Dua endpoint menempatkannya ke dalam alur penyediaan Anda.

Otomatis — setiap klien baru langsung memilikinya. Tandai snapshot sebagai default Anda sekali saja, dan setiap akun yang Anda buat setelahnya akan langsung terpasang dengan snapshot tersebut. Ini mencakup akun yang dibuat melalui POST /v1/subaccounts, akun yang Anda buat di dasbor, dan akun yang dibuat secara otomatis saat klien membayar melalui tautan checkout Anda.

Pertama, temukan id snapshot tersebut:

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

Kemudian atur sebagai default:

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

Itu adalah seluruh integrasinya. Kirim {"snapshot_id": null} untuk mematikannya kembali. Anda dapat melakukan hal yang sama dari dasbor dengan mengeklik bintang di halaman Snapshots.

Untuk membaca apa yang saat ini dibintangi (misalnya, sebelum skrip penyediaan memutuskan apakah akan menetapkan satu), GET /v1/snapshots/default mengembalikan { "success": true, "data": { "default_snapshot_id": "SNAPSHOT_ID" } } — null jika tidak ada yang dibintangi. GET /v1/snapshots (digunakan untuk menemukan id di atas) mengembalikan default_snapshot_id yang sama bersama dengan array snapshots lengkap, jadi sebagian besar integrasi hanya memerlukan satu panggilan tersebut. Bidang objek snapshot lengkap ada di panduan Snapshots.

Sesuai permintaan — instal ke dalam satu akun. Berguna untuk onboarding klien yang sudah ada, atau untuk memberikan templat kedua kepada klien di kemudian hari.

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

Hilangkan sub_account_id dan snapshot akan terinstal ke akun agensi Anda sendiri. Seperti endpoint /subaccounts, ini menyebutkan akun target di jalur atau badan alih-alih melalui parameter sub_account_id yang ada.

Hal yang perlu diketahui sebelum Anda membangunnya:

• Agen yang diinstal dimulai dalam keadaan dijeda. Hubungkan saluran klien terlebih dahulu, lalu aktifkan agen. Hal ini berlaku untuk jalur otomatis maupun sesuai permintaan.
• Penyediaan tidak akan pernah gagal karena snapshot. Jika instalasi tidak dapat diselesaikan, akun klien tetap dibuat dan dapat digunakan — akun tersebut hanya akan kosong dan Anda dapat menerapkan snapshot setelahnya.
• Saluran, kalender, dan koneksi OAuth tidak pernah disalin. Setiap akun menghubungkan salurannya sendiri. Alat yang menggunakan kunci API biasa akan tetap berfungsi secara langsung.
• Menerapkan dua kali akan membuat salinan kedua. Tidak ada yang ditimpa.

Membangun templat itu sendiri melalui API #

POST /v1/snapshots · agen, fungsi kustom, dan media melalui API

Bagian di atas mendistribusikan snapshot yang dibuat seseorang di dasbor. Bagian penulisan juga diekspos, sehingga seluruh siklus — menyusun pengaturan utama sekali, menangkapnya, menyerahkannya ke setiap klien — dapat dijalankan dari kode.

Bagian-bagiannya, dalam urutan yang digunakan oleh skrip penyediaan:

1. Buat fungsi kustom Anda. POST /v1/custom-functions membuat satu; GET /v1/custom-functions mencantumkan apa yang Anda miliki, dan GET, PUT, serta DELETE pada /v1/custom-functions/{customFunctionId} membaca, memperbarui, dan menghapus satu fungsi. POST /v1/custom-functions/test melakukan uji coba definisi sebelum Anda menyimpannya.
2. Buat dan bentuk agen. POST /v1/agents membuatnya, PUT /v1/agents/{agentId} memperbaruinya, dan PATCH /v1/agents/{agentId}/active dengan { "active": false } menjaganya tetap dijeda saat Anda bekerja (panggilan yang sama dengan true membuatnya aktif). GET /v1/agents mencantumkan agen-agen tersebut.
3. Berikan kemampuan pada agen. POST /v1/agents/{agentId}/custom-functions dengan { "custom_function_id": "..." } melampirkan fungsi ke agen; DELETE /v1/agents/{agentId}/custom-functions/{customFunctionId} yang sesuai akan melepaskannya.
4. Isi pustaka media. POST /v1/agents/{agentId}/media-library mengunggah item (JSON dengan base64Data, mimeType, title, description); GET mencantumkan item agen, dan PATCH/DELETE pada /{itemId} memperbarui atau menghapus satu item.
5. Tangkap sebagai 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
  }'

Dari sana, langkahnya sama seperti bagian sebelumnya: tandai sebagai default agar setiap klien baru memilikinya sejak awal, atau terapkan sesuai permintaan. Pemeliharaan tersedia di sampingnya: PATCH /v1/snapshots/{snapshotId} dengan { "name": "..." } mengganti nama, DELETE /v1/snapshots/{snapshotId} menghapus satu snapshot (dan menghapus tanda bintang jika itu adalah default), dan GET /v1/snapshots/apply-targets mencantumkan setiap akun yang dapat Anda instal.

Titik akhir agen, fungsi kustom, dan media semuanya menerima sub_account_id, sehingga panggilan yang sama juga dapat mengelola agen secara langsung di dalam akun klien. Panggilan snapshot selalu bertindak pada akun agensi Anda — templat tersebut tersimpan bersama Anda. Skema permintaan dan respons lengkap untuk semua ini ada di Referensi API.

Kelola tingkat harga Anda melalui API #

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

Paket yang Anda jual di Mode SaaS → Tingkat Harga dapat dibaca dan diubah dari kode, sehingga panel admin atau skrip penyediaan Anda sendiri dapat menambahkan paket, menyesuaikan harga, atau memberikan tautan checkout tanpa perlu membuka dasbor. Lakukan autentikasi dengan kunci API agensi Anda seperti panggilan lainnya di halaman ini; endpoint ini berada di tingkat agensi, sehingga tidak memerlukan sub_account_id. Setiap penulisan menjalankan validasi yang sama dan sinkronisasi produk-dan-harga Stripe yang sama seperti penyimpanan dasbor, jadi paket yang dibuat di sini tidak dapat dibedakan dari paket yang Anda buat secara manual.

Cantumkan tingkat harga Anda #

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

Respons

{
  "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
  }
}

Setiap tingkat harga akan muncul dengan tierIndex-nya — posisinya dalam daftar Paket Anda, yang merupakan cara tiga panggilan lainnya merujuknya — dan checkout_url yang siap dibagikan, tautan yang sama dengan yang diberikan tab Pembayaran kepada Anda, yang sudah mengarah ke domain label putih tempat paket tersebut dijual.

Tambahkan tingkat harga #

Isinya adalah satu objek tingkat harga; objek tersebut ditambahkan ke akhir daftar Anda.

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

Responsnya membawa tingkat harga yang dibuat, termasuk tierIndex tempatnya berada dan checkout_url-nya.

Edit tingkat harga #

Kirim hanya kolom yang ingin Anda ubah; semua hal lain pada paket tersebut dibiarkan seperti semula.

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

Kolom yang tidak dikenali oleh API akan ditolak, bukan diabaikan, dan pesan kesalahan akan menyebutkannya — sehingga kesalahan ketik tidak akan pernah secara diam-diam menulis pengaturan yang terlihat aktif tetapi tidak melakukan apa pun. Mengubah harga, kredit, mata uang, atau siklus penagihan akan membuat harga baru di Stripe Anda; klien yang sudah berlangganan tetap menggunakan paket yang mereka daftarkan.

Hapus tingkat harga #

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

Aturan yang sama dengan dasbor: paket yang masih memiliki pelanggan aktif tidak dapat dihapus. Permintaan akan ditolak, memberi tahu Anda berapa banyak pelanggan yang ada di paket tersebut — batalkan atau migrasikan mereka terlebih dahulu. Penghapusan yang berhasil akan merespons dengan sisa tingkat harga Anda, yang sudah dinomori ulang.

Kolom pada tingkat harga #

Bidang uji coba hanya berarti jika paket memiliki uji coba: simpan paket dengan trial_days: 0 dan bidang tersebut akan dihapus. ID produk dan harga Stripe untuk paket dikelola untuk Anda dan tidak dapat diatur secara manual.

Tiga hal yang perlu diperhatikan:

• Indeks tingkatan adalah posisi, bukan ID permanen. Menghapus paket akan menggeser setiap paket setelahnya ke bawah, jadi ambil ulang daftar tersebut setelah ada perubahan — dan salin ulang tautan checkout yang telah Anda publikasikan, persis seperti yang Anda lakukan setelah menghapus paket di dasbor.
• Mode SaaS harus disiapkan terlebih dahulu. Endpoint ini memerlukan akun agensi dengan pelabelan putih (white labeling) dan kunci Stripe yang sudah disimpan; tanpa itu, tidak ada akun Stripe tempat produk dan harga paket tersebut berada.
• Dua puluh paket adalah batas maksimalnya, sama seperti di dasbor. Bidang max_tiers dalam respons daftar memberi tahu Anda batas saat ini.

Skema permintaan dan respons lengkap ada di Referensi API, di bawah Agensi.

Tetapkan harga per-kredit Anda melalui API #

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

Harga yang dibayarkan klien untuk isi ulang ad-hoc (Mode SaaS → Penetapan Harga Per-Kredit) juga dapat dibaca dan diubah dari kode. Fitur ini dibuat untuk kasus di mana harga harus berubah dengan sendirinya: agensi yang menjual kredit dalam satu mata uang tetapi menagih dalam mata uang lain dapat membiarkan pekerjaan terjadwal merevisi harga seiring perubahan nilai tukar, alih-alih seseorang mengeditnya secara manual setiap minggu.

Membaca harga saat ini #

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

Respons

{
  "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 adalah harga terendah yang diizinkan platform dalam mata uang tersebut, sehingga pekerjaan dapat memeriksa harga baru sebelum mengirimkannya. Ketiga nilai tersebut adalah null sampai harga ditetapkan.

Mengubahnya #

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

Kirim hanya apa yang ingin Anda ubah. price_per_credit_cents adalah harga dalam unit mata uang terkecil (130 = R$1,30); currency adalah kode ISO huruf kecil; note adalah baris opsional hingga 200 karakter yang ditampilkan kepada klien tepat di bawah harga per-kredit di halaman Penagihan mereka — berguna untuk harga referensi dalam mata uang lain, seperti “USD 0,25 per kredit pada kurs referensi kami”. Kirim "note": "" untuk menghapusnya. Responsnya memiliki bentuk yang sama dengan pembacaan di atas, sehingga pekerjaan dapat membandingkan dan melewati penulisan jika tidak ada yang berubah.

Aturan yang sama berlaku seperti di dasbor: harga tidak boleh di bawah minimum platform untuk mata uang tersebut, dan akun memerlukan pelabelan putih (white labeling). Tidak seperti endpoint tingkat harga, tidak diperlukan kunci Stripe untuk membaca atau mengubah nilai ini.

Berikan kunci pada pekerjaan yang tidak dapat melakukan hal lain #

Memasukkan kunci agensi lengkap Anda ke dalam penjadwal memberikan akses yang lebih luas daripada yang dibutuhkan oleh pembaruan harga. Sebagai gantinya, buatlah kunci cakupan (scoped key) yang dibatasi pada area Harga Kredit Agensi: kunci tersebut hanya dapat membaca dan mengubah harga per kredit dan tidak ada yang lain — kunci tersebut tidak dapat menyentuh sub-akun, paket, kredit, atau koneksi Stripe Anda.

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

Respons tersebut membawa kunci baru di api_key satu kali — kunci tersebut tidak akan pernah ditampilkan lagi, jadi simpanlah segera. Atur "read_only": true untuk kunci yang hanya perlu membaca harga, dan tambahkan "expires_at" (tanggal ISO) jika Anda ingin kunci tersebut berhenti berfungsi secara otomatis. Hanya kunci pemilik akun yang dapat membuat kunci cakupan; buat daftar atau cabut kunci tersebut dengan GET /v1/api-keys dan DELETE /v1/api-keys/{id}.

Biarkan sub-akun membaca harga Anda #

GET /v1/subaccounts/agency-pricing

Setiap titik akhir lain di halaman ini dipanggil dengan kunci agensi Anda, yang secara opsional menargetkan klien melalui sub_account_id. Yang satu ini sebaliknya: dipanggil dengan kunci API sub-akun itu sendiri, tanpa sub_account_id, sehingga halaman isi ulang klien sendiri (atau integrasi yang Anda buat untuk mereka) dapat menampilkan apa yang Anda bebankan kepada mereka tanpa pernah melihat akun agensi Anda.

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

Respons

{
  "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"
  }
}

Ini mencerminkan dengan tepat apa yang dikembalikan GET /v1/agency/pricing-tiers dan GET /v1/agency/credit-price untuk Anda sebagai agensi, dikurangi apa pun yang tidak perlu dilihat oleh klien (id Stripe, max_tiers, dan sebagainya). Ini hanya berfungsi untuk akun yang sebenarnya merupakan sub-akun dengan agensi tertaut — memanggilnya dari akun agensi Anda sendiri akan mengembalikan kesalahan izin.

Hal-hal yang perlu diperhatikan #

• Gunakan kunci agensi Anda. Autentikasi setiap panggilan dengan kunci API akun agensi Anda — bukan akun sub-akun. Parameter sub_account_id adalah yang mengarahkan tindakan tersebut.
• Kredit berasal dari sub-akun. Pembelian dan biaya berulang akan memotong saldo kredit sub-akun yang ditargetkan, bukan saldo Anda.
• 404 berarti “bukan sub-akun Anda.” Periksa kembali id dan pastikan akun tersebut adalah akun yang Anda kelola.
• Parameter ini bersifat opsional di mana pun parameter tersebut diterima. Abaikan parameter ini dan endpoint yang sama akan bertindak pada akun agensi Anda, sehingga Anda dapat menggunakan kembali satu integrasi untuk keduanya.

Terkait #

• Akses API — autentikasi, URL dasar, kesalahan, batas kecepatan.
• Sub-Akun — daftar dan kelola akun yang dapat Anda targetkan.
• Isi Ulang Otomatis Sub-Akun — berikan kredit ke sub-akun melalui webhook + API.
• API Kampanye — buat, perbarui, dan salin kampanye, termasuk referensi bidang lengkap.
• API Koneksi Saluran — hubungkan saluran klien dan arahkan ke kampanye.
• Panduan API Analitik (di bagian API) — rollup sub-akun agensi dan setiap titik akhir pelaporan lainnya.
• Snapshots — apa yang ditangkap oleh snapshot dan cara membangunnya di dasbor.