API עבור סוכנויות #

כסוכנות, באפשרותך להשתמש באותו REST API שבו משתמשים הלקוחות שלך, אך להפנות בקשות בודדות לאחד מחשבונות המשנה המנוהלים על ידך במקום לחשבון האישי שלך. זה מאפשר לך לבנות כלים שמבצעים אונבורדינג (onboarding) מלא ללקוח — יצירת סוכני ה-AI שלו, אימון ה-AI על בסיס ידע, ייבוא אנשי קשר, חיבור ערוצי הודעות ורכישת מספרי טלפון — הכל מבלי להיכנס ידנית לכל חשבון משנה בנפרד.

דף זה מכסה רק את ההתנהגות הספציפית לסוכנויות: כיצד לפעול בשם חשבון משנה באמצעות הפרמטר sub_account_id. עבור היסודות (יצירת מפתח, אימות, כתובת URL בסיסית, פורמט שגיאות, מגבלות קצב), התחל עם המדריך גישה ל-API. כל מה שכתוב שם תקף גם כאן — אתה מבצע אימות עם מפתח ה-API של חשבון הסוכנות שלך.

כיצד עובדת הפעולה “בשם” #

כברירת מחדל, כל בקשת API פועלת על החשבון שבבעלותו מפתח ה-API — חשבון הסוכנות שלך. כדי לפעול במקום זאת על חשבון לקוח מנוהל, הוסף לבקשה את הפרמטר האופציונלי sub_account_id, והגדר אותו למזהה החשבון של אותו לקוח.

• השמטת sub_account_id → הבקשה פועלת על חשבון הסוכנות שלך.
• הכללת sub_account_id → הבקשה פועלת על חשבון המשנה ההוא, אך רק לאחר שהפלטפורמה מאשרת שחשבון המשנה אכן שייך לך.

אתה תמיד מבצע אימות עם מפתח ה-API של חשבון הסוכנות שלך. לעולם אינך זקוק למפתח של חשבון המשנה עצמו, ולעולם אינך מטפל בפרטי ההתחברות של חשבון המשנה.

היכן למקם אותו #

• נקודות קצה מסוג GET / DELETE ← העבר אותו כפרמטר שאילתה: ?sub_account_id=THE_SUB_ACCOUNT_ID (לצד ה-apiKey שלך, אם אתה מבצע אימות באמצעות שאילתה).
• נקודות קצה מסוג POST / PUT / PATCH ← כלול אותו בגוף הבקשה בפורמט JSON בתור "sub_account_id": "THE_SUB_ACCOUNT_ID".
• עוזרי AI ← אין צורך להגדיר דבר. שרת ה-MCP נושא את אותה הגדרה בכלים שלו, כך שחיבור אחד עם מפתח הסוכנות שלך יכול לדווח על כל לקוח: פשוט ציין את שם הלקוח בבקשה שלך (“כמה אנשי קשר יש ל-Bella’s Bistro?”). פעולות כתיבה זמינות גם הן: כל נקודת קצה שמקבלת sub_account_id נחשפת ככלי, כך שתוכל ליצור, לשנות ולשלוח בשם הלקוח מאותו החיבור.

מציאת מזהה של חשבון משנה #

ה-sub_account_id הוא המזהה הייחודי של חשבון הלקוח. ניתן לקבל את רשימת חשבונות המשנה שלכם ואת המזהים שלהם מנקודות הקצה של ה-API מסוג SubAccounts (ראו את המדריך חשבונות משנה) או מדף חשבונות משנה בסרגל הצד.

הבעלות מאומתת תמיד #

כאשר אתה מעביר sub_account_id, הפלטפורמה בודקת שהחשבון הוא חשבון משנה אמיתי ושהוא שייך לסוכנות שלך. רק אז הבקשה עוברת.

אם המזהה אינו מוכר, אינו חשבון משנה, או שייך לסוכנות אחרת, הבקשה תיכשל עם תגובת 404:

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

למה 404 ולא 403? תגובת “אסור” (forbidden) תגלה לגורם חיצוני שהמזהה קיים אך אינו שייך לו. החזרת אותו 404 עבור “לא קיים” ו-“לא שייך לך” מבטיחה שלא ניתן להשתמש בנקודת הקצה כדי לגלות אילו מזהי חשבונות שייכים לסוכנויות אחרות. התייחס ל-404 כאן כאל “זה אינו חשבון משנה שאתה מנהל”.

היכן sub_account_id נתמך #

sub_account_id מתקבל כמעט בכל נקודת קצה של משאב — כל קריאה שיוצרת, קוראת, מעדכנת או מוחקת נתונים השייכים לחשבון. בפועל, באפשרותך להקצות ולהריץ את כל ההגדרה של חשבון משנה באמצעות מפתח הסוכנות שלך:

• הגדרת AI — קמפיינים, סוכנים, שאלות נפוצות, מקורות בסיס ידע (סריקת אתרים והעלאת מסמכים), קבוצות בסיס ידע, שידורים, פונקציות מותאמות אישית, שרתי MCP
• אנשי קשר ו-CRM — אנשי קשר (כולל ייבוא), רשימות, תגיות, משימות, עסקאות, פגישות, אירועים
• ערוצים ומספרים — חיבור WhatsApp / WhatsApp Web / Telegram / Instagram & Messenger / LINE, חיפוש / רכישה / ניהול מספרי טלפון, תבניות WhatsApp, ניתוב ערוצים
• הודעות ותוכן — שליחת הודעות, סשנים של צ’אט, ייצוא צ’אטים, סיכומים יומיים
• הגדרות ואינטגרציות — Webhooks, הגדרות ווידג’ט צ’אט, הגדרות White-label, הגדרות BYOK SMS והגדרות חשבון אחרות, אנליטיקה, יומן שגיאות

בכל אחד מאלה, הפרמטר הוא אופציונלי — אם תשמיט אותו, הקריאה תתבצע מול חשבון הסוכנות שלך, כך שאינטגרציה אחת משרתת את שניהם. קרדיטים ושימוש תמיד נגזרים מהחשבון שאליו אתה מכוון: חיובים עבור תשובות AI, הודעות, תגיות ומספרים של חשבון משנה יורדים מיתרת חשבון המשנה.

היכן זה לא חל #

מספר נקודות קצה הן ברמת הסוכנות או מופנות לעצמן ומתעלמות מ-sub_account_id:

• ניהול תתי-החשבונות עצמם — נקודות הקצה של SubAccounts (יצירה / הצגה / עדכון של תת-חשבון) ונקודת הקצה של מגבלת ההוצאות BYOK כבר מציינות את תת-החשבון בנתיב ה-URL שלהן. נקודות הקצה של תמחור ומדיניות ונקודות הקצה של ניטור צ’אט פועלות לפי אותו דפוס.
• העתקת סוכן בין חשבונות — POST /v1/subaccounts/agents/copy מציין את שני החשבונות בעצמו, ולוקח את היעד בתור targetUserId. ראה את הדוגמה המעשית להלן. (ה-POST /v1/subaccounts/campaigns/copy הישן יותר פועל באותה דרך אך הוא אינו מומלץ לשימוש יחד עם שאר ה-Campaigns API.)
• התאמת קרדיטים, ושני סיכומים ברמת הסוכנות כולה — POST /v1/subaccounts/credits מזהה את תת-החשבון באמצעות email במקום זאת; GET /v1/subaccounts/credit-usage ו-GET /v1/subaccounts/campaign-status מדווחים על כל תת-חשבון בבת אחת, כך שאין חשבון יחיד למקד אליו את הפעולה.
• החשבון של הסוכנות שלך — ניהול מפתחות API, דיווח על שימוש בסוכנות, ניהול צוות ודרגות התמחור שלך פועלים תמיד על חשבון הסוכנות שלך.
• הוספת אנשי קשר לרשימה או הסרתם ממנה: POST / DELETE /v1/contacts/lists ו-POST /v1/contacts/lists/batch פועלים על החשבון שבבעלותו המפתח. יצירה, עריכה ומחיקה של הרשימות עצמן (/v1/lists) אכן דורשות sub_account_id.
• Webhooks של הודעות נכנסות — נקודות קצה שמערכות חיצוניות שולחות אליהן מידע (post) קשורות לחשבון שהגדיר אותן באמצעות אישורי הגישה שלו, לכן אין מה להפנות מחדש.

הרשימה המעודכנת תמיד, הניתנת לקריאה על ידי מכונה, של הפרמטרים שכל נקודת קצה מקבלת נמצאת בהפניית ה-API בלוח הבקרה שלכם (הגדרות ← אינטגרציות ← מפתח API) ובמפרט ה-OpenAPI בכתובת GET /v1/docs/openapi.yaml. אנו מפיצים שינויי API לעיתים קרובות — התייחסו אליהם כמקור האמת.

הצג את חשבונות המשנה שלך, או בדוק אימייל אחד #

GET /v1/subaccounts

כאשר קוראים לפונקציה ללא פרמטרים, היא מחזירה את כל חשבונות המשנה תחת הסוכנות שלך במערך data. הוסף את פרמטר השאילתה האופציונלי email כדי לחפש לקוח בודד:

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

• האימייל שייך לאחד מחשבונות המשנה הפעילים שלך ← HTTP 200, עם החשבון הספציפי בלבד: { "success": true, "data": { ... } }.
• הוא לא שייך ← HTTP 404, Agency Sub Account not found.

אין פרמטר שמשיב ב"כן" או “לא” פשוט, לכן יש לקרוא את קוד הסטטוס: 200 אומר שהאימייל הוא אחד מהלקוחות שלך, 404 אומר שלא. חשבונות משנה שנמחקו אינם נכללים, לכן חשבון שהסרת יופיע גם הוא כ-404.

כל חשבון חוזר עם הפרופיל שלו, ההגדרות שלו, מגבלות השימוש שלו והתכונות שהופעלו בו, שזה כל מה שצריך כדי להציג שורת לקוח בלוח הבקרה שלך.

התגובה לעולם אינה נושאת אישורי גישה. מפתחות API, סיסמאות, אסימוני התחברות ופרטי הערוצים שלקוח חיבר (Twilio, Google, Meta ו-bring-your-own-key) מוסרים לפני השליחה. אין פרמטר לבחירת השדות שברצונך לקבל, לכן קרא את השדות הדרושים לך והתעלם מהשאר.

דורש גישת API וחשבון סוכנות.

יצירת חשבון לקוח #

POST /v1/subaccounts

יצירת החשבון מתבצעת בקריאה אחת עם האימייל, השם ושם העסק של הלקוח. כדאי לדעת כמה דברים לפני שאתה בונה את תהליך ההרשמה עבורו.

אינך יכול לבחור את הסיסמה. אין שדה סיסמה: סיסמה נוצרת עבורך ומוחזרת פעם אחת בלבד, כ-temporary_password בתגובת ה-201. שמור אותה או העבר אותה מיד, מכיוון ששום דבר לא יציג אותה בפניך שוב. הלקוח יכול לשנות אותה מהפרופיל שלו, או לאפס אותה ממסך ההתחברות.

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

שום דבר לא נשלח באימייל ללקוח אלא אם תבקש זאת. כברירת מחדל, החשבון נוצר בשקט, ועדכון הלקוח הוא באחריותך. שלח send_account_info_to_sub_account: true והם יקבלו אימייל ברוכים הבאים עם כתובת האימייל שלהם, אותה סיסמה זמנית וקישור להתחברות, הכל תחת דומיין ה-white-label שלך ותחת המותג שלך.

הדגל מכסה רק את כתובת האימייל של הלקוח. הסוכנות שלך תמיד מקבלת הודעת נוצר חשבון משנה חדש, אך היא לעולם אינה מכילה את הסיסמה: מטעמי אבטחה, התגובה 201 היא המקום היחיד שבו ניתן לקבל אותה. אם היא אובדת, הלקוח מגדיר סיסמה משלו באמצעות שכחתי סיסמה במסך ההתחברות.

הזיכויים הראשוניים ניתנים להגדרה על ידך. usage_limits.credits הוא מגבלת ההוצאה ההתחלתית של הלקוח ו-usage_limits.monthly_credits היא הקצבה החודשית החוזרת. שלח "credits": 0 והחשבון יתחיל ללא יתרה לשימוש; השאר את credits ריק והוא יתחיל עם יתרה חד-פעמית של 100 זיכויים כדי שה-AI יוכל להשיב באופן מיידי. אף אחת מהאפשרויות לא גורעת דבר ממאגר הסוכנות שלך בעת היצירה: המאגר שלך יחויב רק כאשר הלקוח ישתמש בפועל בזיכויים.

שמות עסקים חייבים להיות ייחודיים בתוך הסוכנות שלך. שניים מהלקוחות שלך לא יכולים להיקרא שניהם “Client Co”, מכיוון שהשם הזה הוא מה שמזהה את החשבון בלוח הבקרה ובדוחות שלך. שמות של סוכנויות אחרות אינם רלוונטיים לכך.

כאשר הקריאה נכשלת:

מחיקת חשבון לקוח #

DELETE /v1/[email protected] (או ?uid=SUB_ACCOUNT_UID)

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

פעולה זו זהה ללחיצה על כפתור המחיקה בדף חשבונות המשנה, ולא ניתן לבטלה. הלקוח ננעל מחוץ למערכת באופן מיידי ואינו נספר עוד במכסת הלקוחות הכוללת שלך; השיחות, אנשי הקשר, הסוכנים והערוצים המחוברים שלו נמחקים ברקע במהלך הדקות הקרובות. תוכנית שהלקוח רכש דרך עמוד התשלום שלך מבוטלת.

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

• העבר את email או את uid. אם תעביר את שניהם, עליהם לציין את אותו לקוח.
• ניתן למחוק רק לקוחות שלך. כל אימייל או uid אחר, או לקוח שכבר נמחק, יחזירו 404.
• קריאה חוזרת בזמן שהמחיקה עדיין מתבצעת תחזיר 200 עם "status": "already_in_progress".
• לעוזרי AI המחוברים דרך שרת ה-MCP יש כלי זה כ-delete_subaccount בעת חיבור לכתובת ה-MCP הסטנדרטית (כלי סוכנות מושמטים מכתובת MCP ב-white-label).
• כדי לעצור לקוח לזמן מה מבלי לאבד דבר, השהה אותו במקום: הגישה שלו נחסמת, הכל נשמר, וקריאה אחת מחזירה אותו לפעילות.

דוגמה מעשית: חיבור Instagram ו-Messenger עבור חשבון משנה #

חיבור Instagram ו-Messenger הוא תהליך מבוסס דפדפן. אתה מתחיל אותו באמצעות ה-API, מעביר את כתובת ה-URL להסכמה שחזרה ללקוח (או פותח אותה עבורו), ממתין שהוא יאשר בדפדפן שלו, ואז בוחר איזה דף לחבר — כל זאת תוך מיקוד בחשבון המשנה שלו באמצעות sub_account_id.

שלב 1 — התחלת החיבור #

קרא לנקודת הקצה של החיבור עם ה-sub_account_id של הלקוח בגוף הבקשה. לא נשלחים כאן אישורים; הפלטפורמה מחזירה כתובת URL להסכמה שהלקוח חייב לפתוח בדפדפן, בתוספת אסימון מתאם (correlation token) חד-פעמי.

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

תגובה:

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

שלח את הלקוח ל-oauth_url בדפדפן כדי לאשר. ה-state_token מתאם בין ניסיון זה והוא סוד לטווח קצר — אל תתעד אותו בלוגים. הניסיון יפוג ב-expires_at; אם פג תוקפו, התחל מחדש.

שלב 2 — ביצוע סקר (Polling) עד לטעינת הדפים #

לאחר שהלקוח מאשר, בצעו תשאול (polling) לנקודת הקצה של הסטטוס (עם אותו sub_account_id, הפעם כפרמטר שאילתה) עד להופעת הדפים הניתנים לחיבור.

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

תגובה:

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

השדה status עובר דרך pending → token_received → pages_loaded → connected. המתן ל-pages_loaded לפני בחירת דף. שני מצבי שגיאה סופיים יכולים להופיע גם במקום התקדמות: failed ו-expired (הלקוח סירב להסכמה, או שחלף חלון הזמן של כ-30 דקות של אסימון המצב) — שדה reason כלול כאשר אחד מהם מתרחש. הפסק את התשאול והתחל מחדש בשלב 1 אם אתה רואה אחד מהם; אל תמתין ל-pending לנצח. אסימוני גישה לדף לעולם אינם מוחזרים.

שלב 3 — בחירת הדף לחיבור #

בחרו אחד ממזהי הדפים משלב 2 ובחרו אותו. בחירת דף מחברת גם את אינסטגרם וגם את מסנג’ר עבור אותו דף. כללו את sub_account_id בגוף הבקשה שוב.

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

תגובה:

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

זה הכל — אינסטגרם ומסנג’ר מחוברים כעת לחשבון המשנה של הלקוח. סיפקתם רק את page_id; אישור הגישה הבסיסי נפתר בשרת ולעולם אינו עובר דרך האינטגרציה שלכם.

דוגמה עובדת: רכישת מספר עבור חשבון משנה #

רכישת מספר עובדת באותו אופן: חפשו עם sub_account_id בשאילתה, ולאחר מכן בצעו רכישה איתו בגוף הבקשה. נקודות זכות ינוכו מיתרת חשבון המשנה, והמספר יוקצה לחשבון המשנה.

חיפוש (cURL):

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

רכישה (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();

רכישה (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()

תגובה:

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

המספר מוקצה במצב PURCHASED ורישום שולח ה-WhatsApp נמשך ברקע. בצע תשאול ל-GET /v1/phone-numbers/{phoneNumber}/status?sub_account_id=abc123def456 עד שהסטטוס יגיע ל-ONLINE לפני השליחה.

דוגמה מעשית: העברת סוכן תבנית לכל לקוח חדש #

הדפוס המקובל בסוכנויות הוא לשמור סוכן ראשי אחד בחשבון הסוכנות שלכם, המכוונן כפי שאתם רוצים שכל לקוח יתחיל, ולהטמיע עותק שלו בכל תת-חשבון חדש בזמן ההקצאה. מדובר בשלוש קריאות, ואין צורך לחזור על שום דבר לאחר מכן: העותק שומר על ההגדרות שלו עד שתשנו אותן.

שלב 1 — העתקת הסוכן פנימה #

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

התגובה נושאת את ה-id של הסוכן החדש ב-data.agent_id. השאלות הנפוצות, מאגר הידע וספריית המדיה עוברים יחד איתו; תבניות ה-WhatsApp, הפוסטים החברתיים המחוברים ואנשי הקשר של חשבון המקור אינם עוברים במכוון. רשימת שדות מלאה נמצאת ב-AI Agents API.

שימו לב שנקודת קצה זו מקבלת targetUserId במקום sub_account_id — היא מציינת את שני החשבונות בעצמה. שתי הקריאות להלן משתמשות בפרמטר ה-sub_account_id הרגיל.

שלב 2 — הפעלה #

העותק תמיד מגיע כשהוא מושהה, כך שהוא לא יכול לשלוח הודעות לאף אחד עד שתאשרו זאת. זהו גם הרגע לקבוע את דרגת ה-AI שאתם רוצים שהלקוח יהיה בה; היא נשארת שם, כך שאין צורך להחיל אותה מחדש לפי לוח זמנים.

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

כדי למנוע מהלקוח לשנות את הדרגה לאחר מכן, נעלו את הדרגות המותרות בתת-החשבון במקום לשלוח את הערך מחדש.

שלב 3 — הפניית הערוצים של הלקוח אליו #

העותק מגיע גם ללא ניתוב, כך ששום דבר לא מגיע אליו עד שתגדירו אותו כמי שעונה בערוצים שהלקוח חיבר. קריאה אחת לכל ערוץ:

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

מכאן ואילך, הודעה ראשונה מאיש קשר לא מוכר בערוץ זה תיקלט על ידי הסוכן שהועתק באופן אוטומטי. ראו הפניית ערוץ לסוכן עבור הערוצים האחרים וניתוב לפי מספר.

הגדר את אזור הזמן של הלקוח בעת יצירת חשבון המשנה. העבר את time_zone_id ב-POST /v1/subaccounts. שעות הפעילות של סוכן מוערכות לפי אזור הזמן של חשבון המשנה עצמו, כך שלקוח שנוצר ללא הגדרה כזו, לוח הזמנים שלו ייקרא לפי UTC — מה שמשנה בשקט את הזמנים שבהם מותר לעוזר להשיב.

דלג על אשף ההגדרה עבור לקוח שאתה מגדיר בעצמך #

POST /v1/subaccounts

כברירת מחדל, בפעם הראשונה שבעל חשבון משנה חדש נכנס למערכת, הוא מועבר דרך אשף הגדרה מודרך. עבור לקוחות בשיטת “עשה זאת עבורי” (done-for-you) — שבה אתה בונה את סוכן ה-AI ומחבר את הערוצים לפני שהלקוח נכנס אי פעם — העבר את guided_onboarding: false בעת יצירת החשבון. הם ינחתו במסך הבית הרגיל במקום זאת — לוח הבקרה במחשב, הצ’אטים שלהם בטלפון — והכניסה לאשף ההגדרה תהיה מוסתרת מסרגל הצד שלהם.

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

השמיטו את השדה (או שלחו true) והאשף יתנהג בדיוק כפי שהתנהג תמיד, כך שאינטגרציות קיימות אינן זקוקות לשינוי. כדי להחזיר ללקוח את האשף מאוחר יותר, הציגו מחדש את הפריט guided_onboarding עם PUT /v1/subaccounts/{subAccountUid}/menu-visibility (להלן) — נראות התפריט קובעת אם האשף נגיש, guided_onboarding שולט רק בהפניה מחדש של הכניסה הראשונה.

השבתת משימות, סיכומים יומיים או ספריית המדיה עבור לקוח #

POST /v1/subaccounts

שלושת אלו מופעלים עבור כל לקוח חדש אלא אם ציינת אחרת, והם מתנהגים אחרת מכל תכונה אחרת במדריך זה: הם מבוססים על ביטול הסכמה (opt-out), ולא על הצטרפות (opt-in). השמטתם מ-features אינה מספיקה כשלעצמה, מכיוון שרשימת ה-features של אינטגרציה ישנה פשוט לא הזכירה אותם מעולם — אין לנו דרך להבדיל בין “הסוכנות כיבתה את זה” לבין “הרשימה הזו נכתבה לפני שהאפשרות הייתה קיימת”.

לכן, יש לציין זאת במפורש באמצעות 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
    }
  }'

כל מפתח הוא אופציונלי; כל מה שתשמיט יישאר מופעל. עם tasks: false ה-AI מפסיק ליצור משימות עבור אותו לקוח ולא נשלחים אימיילים מסוג “נוצרה משימה חדשה”; עם daily_summaries: false הסיכום הלילי לעולם לא נוצר ולא נשלח בדוא"ל.

feature_settings הוא הדבר היחיד שמכבה את שלושת אלו בעת היצירה. השמטתם מ-features לא עושה דבר כשלעצמה, ללא קשר לאופן שבו שאר הרשימה שלך נראית — זה מכוון, כדי שאינטגרציה ישנה לא תאבד את שלושתם בשקט.

כדי לשנות זאת לאחר מכן, שלח את רשימת ה-features המלאה ל-PUT /v1/subaccounts/{subAccountUid}/features — שם, נוכחות ברשימה מפעילה תכונה והיעדרות מכבה אותה.

כניסה אוטומטית של לקוחות לחשבון המשנה שלהם (SSO) #

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

קריאה אחת עם מפתח ה-API של הסוכנות שלך מחזירה כתובת URL מוכנה לפתיחה, שמחברת את הלקוח ישירות לחשבון המשנה שלו — ללא מסך התחברות, ללא שלב סיסמה, וללא צורך לבנות דבר מעבר לכך. ניתן לפתוח אותה בלשונית חדשה, כהפניה (redirect), או בתוך iframe במוצר שלך.

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

תגובה

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

איך להשתמש בזה נכון:

• דילוג אחד. פתיחת url מחברת את הלקוח ומעבירה אותו ישירות לדף ה-redirect בלוח הבקרה — ללא מסך התחברות וללא דף ביניים. deep_link_url מציין את אותו יעד עבור אינטגרטורים המעדיפים לנווט למסגרת באופן מפורש לאחר ההתחברות; ברגע שהסשן קיים, כל נתיב בלוח הבקרה יעבוד בהקשר של דפדפן זה.
• הנפקה לפי דרישה, פתיחה מיידית. הקישור מכיל פרטי התחברות ותוקפו פג לאחר כשעה. בקש אותו בצד השרת ברגע שהלקוח לוחץ, ולעולם אל תשמור או תשלח אותו בדוא"ל.
• אסימון ההתחברות עובר בתוך ה-fragment של ה-URL (#…), שדפדפנים לעולם אינם שולחים לשרתים, והוא מוסר משורת הכתובת ברגע שהוא מנוצל.
• חשבונות המשנה שלך בלבד. נקודת הקצה מסרבת לכל חשבון שאינו בבעלות הסוכנות שלך.
• קישור שפג תוקפו מציג שגיאה ברורה עם נתיב לניסיון חוזר — הנפק קישור חדש.

הסתרת פריטי ניווט בחשבון משנה #

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

שולט באילו פריטי סרגל צד והגדרות חשבון משנה רואה — שימושי כאשר אתה מטמיע את לוח הבקרה ורוצה רק את הממשקים שהמוצר שלך עדיין לא מכסה. כל מה שלא מופיע ברשימה נשאר גלוי; שלח null כערך ה-menuVisibility המלא כדי לאפס הכל למצב גלוי. הסתרת פריט מסתירה את כניסת התפריט — שלב זאת עם התכונות שאתה מעניק לחשבון המשנה לצורך חסימה קשיחה.

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

תגובה

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

side_nav מקבל את 13 המפתחות הללו, התואמים לשמות הפריטים בסרגל הצד: Dashboard, DailySummaries, Chats, Contacts, Deals, Tasks, Automations, Campaigns, Appointments, Settings, Help, CreditsCounter (יתרת הקרדיט המוצגת בסרגל הצד) ו-guided_onboarding (אשף ההגדרה). Campaigns מסתיר רק את דף הקמפיינים שיצא משימוש; לדפי סוכני AI ו-שידורים אין מפתח ולא ניתן להסתירם בדרך זו. שלושה מפתחות נוספים — AiInsights, Sub Accounts ו-Agency Reselling — מתקבלים אך אינם עושים דבר: הם היו רלוונטיים רק ללוח הבקרה הקלאסי הישן, כך שהגדרתם אינה משפיעה על חשבונות המשנה שלך. מפתחות חסרים משמעותם שהפריט גלוי; כשאתה נכנס לחשבון המשנה בעצמך, פריטים מוסתרים מוצגים זמנית כדי שתוכל תמיד לשנות את ההגדרות בחזרה.

אותו אובייקט menuVisibility מקבל גם שני שדות אופציונליים עבור לוח המחוונים הראשי של הלקוח. dashboard_widgets ממפה מזהה של ווידג’ט ל-true (מוצג) או false (מוסתר), ו-dashboard_order הוא רשימה של מזהי ווידג’טים לפי הסדר שבו הם צריכים להופיע. המזהים, בסדר ברירת המחדל שלהם, הם kpis, performance, credits (שימוש בקרדיט), funnel, inbox, outcomes, channel_health, ai_cost, ai_human, heatmap (זמנים פעילים ביותר), top_campaigns (סוכנים מובילים), contacts_by_country, activity ו-tasks_deals. מזהים חסרים נשארים גלויים, ומזהים שהושמטו מ-dashboard_order יופיעו בהמשך לפי סדר ברירת המחדל. לדוגמה, "dashboard_widgets": { "credits": false } מסתיר את לוח הקרדיטים מהלקוח.

הסתרת דף מהתפריט לעולם אינה מעניקה גישה אליו. Automations דורש שתכונת ה-automations תהיה מורשית בחשבון המשנה — הגדר את המפתח ל-true בלעדיה והדף עדיין לא יופיע. Tasks ו-DailySummaries עובדים בצורה הפוכה: הם מופעלים עבור כל לקוח אלא אם תכבה אותם (ראה השבתת משימות, סיכומים יומיים או ספריית המדיה עבור לקוח).

בחר אילו סוגי ערוצים לקוח יכול לחבר #

PUT /v1/subaccounts/{subAccountUid}/features

מתגי סוגי ערוצים (Channel Types) שאתה רואה ברמת תוכנית הם מזהי תכונות רגילים, לכן ניתן להגדיר אותם לכל לקוח דרך ה-API במקום דרך לוח הבקרה. זהו אחד מנקודות הקצה (endpoints) שמציינות את חשבון המשנה בתוך ה-URL שלו, לכן הוא לא דורש 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"
    ]
  }'

מה חשוב להקפיד עליו:

• הקריאה מחליפה את כל רשימת הפיצ’רים. שלחו את כל הפיצ’רים שהלקוח צריך לשמור, לא רק את אלו שאתם משנים. אותם מזהים (IDs) עובדים כ-features ב-POST /v1/subaccounts בעת יצירת החשבון.
• סוגי ערוצים ומספר ערוצים הם מגבלות נפרדות, ושניהם חלים. channels_1 / channels_3 / channels_unlimited שולטים בכמה חיבורים יהיו; המזהים של channel_* שולטים באילו סוגים. הדוגמה לעיל פירושה “עד 3 חיבורים, ורק Chat Widget, WhatsApp Web או Instagram”.
• automations_edit, broadcasts_send ו-smart_lists_create מאפשרים ללקוח ליצור, לערוך ולמחוק אוטומציות, שידורים ורשימות חכמות משלו. רשימה שאינה מציינת אף אחד משלושת אלו משאירה אותם כפי שהם (בחשבון משנה חדש: כל השלושה פעילים), כך שאינטגרציה ישנה ממשיכה לעבוד. ציינו לפחות אחד והרשימה תגדיר את כל השלושה: אלו שלא כללתם יכובו. הלקוח עדיין יכול להשתמש במה שהגדרתם עבורו בכל מקרה, ומפתח ה-API של הסוכנות שלכם והסשנים שלכם בחשבון הלקוח לעולם לא יוגבלו על ידי שלושת אלו.
• כל פיצ’ר אחר הוא בדיוק מה שהרשימה מציינת, ביצירה ובעדכון. לקוח שנוצר או עודכן עם רשימת features מקבל את הפיצ’רים האלו ותו לא. זה כולל את crm_erp_integrations (סעיף האינטגרציות של CRM & ERP, שבו לקוח מחבר את Odoo): הוא פעיל רק כאשר הרשימה שלכם כוללת אותו, לכן הוסיפו אותו אם הלקוח צריך לחבר CRM או ERP. לקוח שנוצר ללא רשימת features מקבל את ערכת ברירת המחדל, שכוללת אותו.
• שליחת מזהי channel_* ריקים משמעותה ללא הגבלת ערוצים. זוהי ההתנהגות המקורית, וזו הסיבה שלקוחות קיימים לא הושפעו כאשר זה הושק. שלחו אחד או יותר וכל השאר יוצגו כנעולים בדף הערוצים של הלקוח עם הערת שדרוג במקום כפתור “חיבור”. ערוצים שהלקוח כבר חיבר ימשיכו לעבוד.

הגדרת רשימת הערוצים ברמת תוכנית, כך שכל לקוח שרוכש את אותה תוכנית יירש אותה, מתבצעת בלוח הבקרה תחת הגדרות תוכנית הסוכנות שלך. נקודת קצה זו מגדירה זאת עבור חשבון משנה ספציפי אחד.

הגדרת מגבלה מדויקת של חברי צוות עבור לקוח #

PUT /v1/subaccounts/{subAccountUid}/limits

התכונות של team_seats_* מציעות רק שלבי סולם מוגדרים מראש (3 / 5 / 10 / ללא הגבלה). כדי להעניק ללקוח מספר מדויק של מושבי צוות — 2, 7, 15, או כל מספר אחר — הגדר במקום זאת את usage_limits.team_seats_limit. הגדרה זו גוברת על הערכים המוגדרים מראש, והפלטפורמה אוכפת אותה בכל הזמנה, הוספה ישירה ואישור הזמנה: ברגע שהמגבלה מגיעה למיצוי, הזמנות נוספות נדחות בצד השרת.

• מספר שלם חיובי הוא המכסה המדויקת.
• 0 פירושו שחברי צוות אינם כלולים — הלקוח אינו יכול להזמין איש.
• -1 פירושו ללא הגבלה.
• null מנקה את המגבלה המותאמת אישית וחוזר להסתמך על כל ערך מוגדר מראש של team_seats_* שקיים ברשימת התכונות.

הנמכת המגבלה לעולם אינה מסירה חברי צוות קיימים; היא רק עוצרת הוספה של חברים חדשים.

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

ניתן להגדיר זאת גם בעת היצירה: POST /v1/subaccounts מקבל usage_limits.team_seats_limit עם אותה סמנטיקה. כדי לקרוא את הערך הנוכחי, משוך את חשבון המשנה באמצעות GET /v1/subaccounts?email=... והסתכל על usage_limits.team_seats_limit (בהיעדר/null = הגדרות ברירת המחדל קובעות). אותו נקודת קצה מעדכנת גם את credits, monthly_credits, roll_over_to_next_month, rollover_cap_months, rollover_expiry_days ו-byok_monthly_limit_usd — שלח רק את המפתחות שברצונך לשנות. creditManagementMode ברמה העליונה ("manual" או "reselling") מחליף את מצב האשראי של הלקוח; חשבון משנה שנוצר דרך ה-API מתחיל במצב ידני, לכן העבר אותו ל-"reselling" לפני שהלקוח משלם דרך ה-checkout של מצב ה-SaaS שלך (ראה חשבונות משנה, הרצת תקופת ניסיון בחינם).

כיצד זה משפיע על מגבלות המושבים בתוכניות SaaS. תוכניות ה-SaaS שלך יכולות לכלול הקצאת מושבים משלהן (המוגדרת בעורך התוכניות — ראה מושבי צוות בתוכנית), אשר מוחלת באופן אוטומטי כאשר לקוח נרשם. מגבלה שאתה מגדיר דרך נקודת קצה זו נחשבת להקצאה ידנית: רכישת תוכנית מחליפה אותה בהקצאת המושבים של התוכנית עצמה (רכישה זו היא בחירה מפורשת בתוכנית), אך חידושים חודשיים אוטומטיים לעולם אינם דורסים מגבלה ידנית — כך שחריגה חד-פעמית שאתה מעניק ללקוח נשמרת לאורך מחזור החיוב שלו. ניקוי המגבלה הידנית באמצעות null מחזיר את השליטה בשדה לתוכנית בחידוש הבא שלה.

הגבל את מה שלקוח מעביר בין חידושים. שני מפתחות usage_limits נוספים נמצאים לצד roll_over_to_next_month. שניהם מתקבלים על ידי POST /v1/subaccounts גם בעת היצירה, ו-null מנקה את שניהם.

אם לא יוגדרו, שניהם יחזרו להגדרות התוכנית של הלקוח; ערך שנשלח כאן יגבר על זה של התוכנית. רק קרדיטים חוזרים (ההקצבה החודשית וקרדיטי התוכנית) כפופים להם: תוספות, טעינות אוטומטיות ותוספות חד-פעמיות לעולם אינן מוגבלות או פוקעות. כל צמצום נרשם בהיסטוריית הקרדיטים של הלקוח כ-Rollover Cap Credit Adjustment או Expired Credits Credit Adjustment ולעולם לא נחשב כשימוש. המקבילות ברמת התוכנית הן rollover_cap_months ו-rollover_expiry_days בשכבת תמחור — ראה השדות בשכבה ו-הגבלת מה שמועבר.

הגדרת תמחור ומדיניות AI לכל לקוח #

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

שמונה מתגים נוספים לכל לקוח, לצד /limits, /features ו-/menu-visibility לעיל. כל אחד לוקח את ה-uid של חשבון המשנה ב-URL (ללא sub_account_id גוף/פרמטר שאילתה — היעד כבר מצוין בנתיב) והוא מוגדר באותו אופן: מפתח הסוכנות שלך, וחשבון המשנה חייב להיות שייך לסוכנות שלך.

באילו מודלי AI לקוח יכול להשתמש

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 } מצרפת את הלקוח (או מוציאה אותו) לשכבת ה-Max AI, לפי המחירון של הפלטפורמה. הפעלת אפשרות זו עבור לקוח BYOK משנה את עלות ה-AI שלו מ-“0 קרדיטים, משולם באמצעות המפתח שלי” ל-“חיוב מתוך מאגר הקרדיטים שלי”, לכן מדובר בהחלטה מכוונת לכל לקוח בנפרד ולא בברירת מחדל כלל-סוכנותית.

כדי להגביל באילו שכבות (tiers) סוכני הלקוח יכולים לבחור (במקום רק להגביל את ה-Max), השתמש ב-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 הוא מערך שנשאב מ-standard, economy, max, mini — הוא מחליף את רשימת ההיתרים (allow-list) של הלקוח. שלח null (או []) כדי לנקות את ההגבלה ולאפשר לו לבחור בכל שכבה. רשימה שמוגדרת כאן נחשבת לנעילה ידנית: ה-allowed_ai_tiers של התוכנית עצמה (ראה ניהול שכבות התמחור שלך דרך ה-API) כבר לא משפיע על לקוח זה בעת החידוש. זה חשוב מכיוון שחשבון משנה שבוחר שכבת AI משלו מוציא מהקרדיטים שלך, לכן זהו המנוף לקביעת המודלים שלקוח משווק מורשה להפעיל על חשבונך.

תגובת המתנה בזמן שללקוח אין קרדיטים

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

כאשר היתרה של הלקוח (או המאגר שלך) ריקה, ה-AI לא יכול לענות ואיש הקשר לא שומע דבר. עם enabled: true, כל איש קשר שכותב במהלך ההשבתה מקבל את message פעם אחת (מקסימום 500 תווים, נשלח כפי שהוא בכל ערוץ), וה-AI עונה לשיחות אלו באמת ברגע שהקרדיטים חוזרים. enabled: false שומר את הטקסט שנשמר למועד מאוחר יותר; enabled: false ללא message מסיר את ההגדרה. אותו מתג כמו Holding reply when out of credits בחלון העריכה של חשבון המשנה — ראה תגובת המתנה בזמן שללקוח אין קרדיטים.

מה לקוח משלם עבור כל פעולת AI, ותוספת העמלה של WhatsApp

שתי דרכים להגדיר את התעריף מול הלקוח שלך, מהפשוטה ביותר ועד המפורטת ביותר:

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 הוא המחיר בקרדיטים שהיתרה העצמית של תת-החשבון שורפת עבור כל פעולת AI במודל Max — תוספת העמלה שלך מול הלקוח מעבר למה שהמאגר שלך משלם בפועל. null מנקה את העקיפה חזרה למחיר המחירון של הפלטפורמה. התעריף חייב להיות לפחות מה שפעולת Max עולה למאגר שלך (כך שלעולם לא תוכל לתמחר לקוח מתחת לעלות שלך) ולא יותר מ-10 קרדיטים; בקשה מחוץ לטווח זה תידחה עם הודעת שגיאה המציינת את הרף המינימלי המחושב.

עבור תמחור לפי סוג פעולה במקום תעריף Max אחיד, השתמש ב-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 הוא מיזוג (MERGE) לתוך המפה הקיימת של הלקוח — מפתח שלא ציינת נשאר כפי שהיה, ו-null מבטל את המפתח הזה חזרה לברירת המחדל שלו. המפתחות המוכרים:

שיעורים לכל פעולה חייבים להיות מספר הגדול מ-0 ועד 10; wa_carrier_multiplier חייב להיות לפחות 1 (ללא הנחה מתחת לעלות) ועד 10. שליחת מפתח לא מזוהה, או ערך מחוץ לטווח, תדחה את הבקשה כולה ותציין כל מפתח בעייתי, כך ששגיאת הקלדה לעולם לא תגרום לשמירה שקטה של מחיר שאינו מוחל בפועל.

אם אתם חברים ב-Champions Circle, ה-insider-rate מעביר את תעריף ה-Insider שלכם (20% הנחה על פעולות Max ו-Mini, לידים ואוטומציות של Lead Finder) ללקוח אחד במקום להחיל אותו על כל הסוכנות:

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

הפעלת אפשרות זו דורשת שחשבון הסוכנות שלך יחזיק בפועל בחברות ב-Circle; כיבוי האפשרות אינו דורש זאת לעולם, כך שחבר שחברותו פגה תמיד יכול להחזיר לקוח למצב הקודם.

נעל חלקים מתוכנית העבודה (playbook) של לקוח

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 היא רשימה של מקטעי ה-playbook שיש לנעול, והיא מחליפה את הרשימה הנעולה של הלקוח. שלח את null (או []) כדי לבטל את הנעילה של הכל. שימושי עבור לקוחות בניהול מלא (done-for-you) שבהם אתה הבעלים של ה-playbook ונמדד על פי התוצאות.

סוכנים שנבנו בעורך הנוכחי שומרים את ה-playbook שלהם במקטעים אלו, לכן אלו המקטעים שיש לנעול:

סוכנים נוכחיים לעולם אינם קוראים את instructions, לכן נעילה שלו בלבד לא מגנה על דבר אצלם: נעל את conversation_flow, rules ושאר המקטעים שהלקוח לא אמור לגעת בהם.

לא ניתן לשנות מקטע נעול על ידי אף אחד שמחובר כלקוח: לא על ידי הלקוח עצמו, חברי הצוות שלו, מפתח ה-API שלו, ואפילו לא על ידך כשאתה עובר ללוח הבקרה של הלקוח מחשבון הסוכנות שלך. השינוי נדחה בסוכן הפעיל, בטיוטה שלא פורסמה, וכאשר טיוטה מתפרסמת. כדי לערוך מקטע נעול בעצמך, השתמש ב-API עם מפתח הסוכנות שלך ו-sub_account_id, או בטל את הנעילה, בצע את השינוי, ונעל אותו שוב. מקטעים שלא נעלת נשארים ניתנים לעריכה מלאה.

הגדר את העדפות ההתראות של לקוח בשמו

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

רק הקטגוריות שאתה שולח משתנות: כל אחת מהן ממוזגת מעל ההגדרה הנוכחית של הלקוח, וכל קטגוריה שאתה משמיט שומרת על הערך שלה. כל קטגוריה תחת settings מקבלת enabled (בוליאני) ועד שלושה channels מתוך email, in_app, webhook. שלח null כדי לאפס לברירות המחדל של הפלטפורמה.

כל שבע נקודות הקצה מגיבות ב-{ "success": true, "data": { "subAccountUid": "...", ...the field(s) you set... } }, ומתועדות ביומן ביקורת עם הערך שלפני/אחרי. שגיאות נפוצות: 403 אם החשבון שלך אינו חשבון סוכנות/מפתח או שחשבון המשנה אינו מנוהל על ידך, 400 אם זה אינו חשבון משנה של סוכנות או שערך כלשהו מחוץ לטווח.

השהיית לקוח שהשעה את המנוי שלו #

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

כאשר לקוח משעה את המנוי שלו איתך, השהה את החשבון שלו במקום למחוק אותו: כל מה שהוא שולח נעצר מיד — הודעות יוצאות, שידורים, תשובות AI בכל ערוץ — וכאשר הוא נכנס למערכת, הוא רואה מסך נעילה של חשבון מושהה (עם הודעה אופציונלית ממך) במקום את האפליקציה. דבר אינו נמחק או מתנתק: סוכנים, שידורים, ערוצים מחוברים, אנשי קשר והיסטוריית צ’אט נשארים בדיוק כפי שהם, כך שביטול ההשהיה מחזיר את הלקוח בדיוק לנקודה שבה עצר — ללא צורך בהגדרה מחדש.

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

תגובה

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

כאשר הלקוח חוזר, POST /v1/subaccounts/SUB_ACCOUNT_UID/unpause (ללא גוף הודעה) מסיר את הנעילה — שליחת הודעות ותשובות AI מתחדשות מיד.

כדאי לדעת:

• זהו אותו מצב כמו מתג ה-Hard blocked בלוח הבקרה (חסימה / השהיה של תת-חשבון) — לקוח שהושהה דרך ה-API יופיע כחסום בלוח הבקרה ולהיפך, וביטול השהיה מסיר חסימה שבוצעה מכל צד. המצב הנוכחי ניתן לקריאה מהשדה agency_block ב-GET /v1/subaccounts (level של "none", "soft_blocked" או "hard_blocked").
• שתי הקריאות הן אידמפוטנטיות. השהיית לקוח שכבר מושהה רק מרעננת את ההודעה, הסיבה וחותמת הזמן; ביטול השהיה של לקוח פעיל לא משנה דבר.
• הלקוח לא מקבל אימייל באופן אוטומטי — סוכנויות רבות משתמשות ב-white-label, לכן העדכון של הלקוח נשאר באחריותך.
• החיוב שלך ב-DM Champ נותר ללא שינוי. השהיית לקוח משפיעה רק על מערכת היחסים שלך איתו.
• עוזרי AI יכולים לעשות זאת גם: שרת ה-MCP חושף נקודות קצה אלו ככלים pause_subaccount ו-unpause_subaccount בכתובת ה-MCP הסטנדרטית (כלי סוכנות מושמטים מכתובת MCP ב-white-label).

הענקת או הפחתת קרדיטים ישירות #

POST /v1/subaccounts/credits

מוסיף או מסיר כמות מדויקת של קרדיטים מיתרת חשבון משנה אחד — המקבילה ב-API להתאמת קרדיט ידנית בלוח הבקרה. זהו שינוי יתרה חד-פעמי, נפרד מהגדרות ה-monthly_credits, roll_over_to_next_month, rollover_cap_months ו-rollover_expiry_days החוזרות ב-PUT /v1/subaccounts/{subAccountUid}/limits.

זוהי נקודת הקצה היחידה בדף זה שמזהה את חשבון המשנה לפי דוא"ל ולא לפי sub_account_id.

ניסיון חוזר בטוח. שלח את אותו מפתח אידמפוטנטיות (idempotency key) בעת ביצוע ניסיון חוזר לקריאה, למשל לאחר פסק זמן, ונקודות הזכות יתווספו או יוסרו פעם אחת בלבד. במשך 24 שעות, חזרה על הפעולה עם אותו מפתח ואותם פרטים תחזיר את התשובה הראשונה שוב (עם כותרת Idempotent-Replayed: true) במקום לשנות את היתרה פעם נוספת. אותו מפתח עם אימייל, סכום או תיאור שונים יידחה (422), וחזרה על הפעולה שמגיעה בזמן שהקריאה הראשונה עדיין רצה תקבל 409: המתן רגע ונסה שוב. קריאות ללא מפתח פועלות כפי שפעלו בעבר.

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

תגובה

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

amount שלילי שיביא את היתרה אל מתחת לאפס יידחה עם 400, תוך ציון היתרה הזמינה והסכום שניסית להפחית. אם הלקוח נמצא במצב מכירה חוזרת (reselling), סכום שנוסף נחשב כנקודות זכות שהלקוח רכש: הוא נלקח ממאגר נקודות הזכות של הסוכנות שלך באותו רגע, בדיוק כמו רכישה דרך עמוד התשלום שלך, והוא נשמר לאחר האיפוס החודשי הבא שלהם בדיוק כפי שהיה קורה בטעינה רגילה. כאשר המאגר שלך אינו יכול לכסות את הסכום, הקריאה נדחית עם 402 ושום דבר לא משתנה, לכן עליך לטעון את יתרת הסוכנות שלך תחילה. הפחתה אצל לקוח במצב מכירה חוזרת מסירה את נקודות הזכות מהלקוח בלבד; דבר אינו מוחזר למאגר שלך. אצל לקוח עם הקצאה סטנדרטית, תוספת נחשבת כחלק מהקצבה החוזרת שלו ואינה גורעת דבר מהמאגר שלך עד שהלקוח משתמש בה. כך או כך, מדובר בתוספת חד-פעמית, לכן מגבלת גלגול (roll-over cap) או תאריך תפוגה שהוגדרו בחשבון (או בתוכנית שלו) לעולם לא יקצצו אותן — רק ההקצבה החוזרת ונקודות הזכות של התוכנית כפופות להם.

קריאת שיחות של חשבון משנה #

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

מאפשר לך לבנות תצוגת ניטור או תמיכה בשיחות של לקוח מבלי להיכנס לחשבון שלו. ראשית, הצג את רשימת אנשי הקשר שלו עם תצוגה מקדימה של ההודעה האחרונה, ולאחר מכן קרא את היסטוריית ההודעות המלאה של איש קשר אחד.

הצגת אנשי קשר

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

תגובה

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

אנשי הקשר מסודרים לפי הפעילות האחרונה ביותר תחילה. המשך לדפדף עם lastActivityAt כל עוד hasMore הוא true.

קריאת הודעות של איש קשר אחד

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

תגובה

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

ההודעות חוזרות מהחדשה ביותר לישנה ביותר; דפדף אחורה בהיסטוריה עם beforeTimestamp.

קריאת ניצול קרדיט ובריאות קמפיינים בכל החשבונות שלך #

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

שני סיכומים בסגנון לוח בקרה עבור כל חשבון משנה שאתה מנהל, לצורך בניית דוחות סוכנות משלך במקום להיכנס לכל לקוח בנפרד.

ניצול קרדיט

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

העבר את subAccountId והתגובה תכלול גם את records: חיובים בודדים עם amount, reason, campaignName, contactName ו-timestamp. לקוח שמוציא כספים באמצעות מפתח BYOK משלו במקום הקרדיטים שלך, נתוני העלות/אסימונים שלו יוסתרו (costsRedacted: true) — זוהי טלמטריה של עלויות פלטפורמה, לא משהו שנועד להצגה לצופה בדרגת משווק. |

סטטוס קמפיין

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

כל שורה מכילה גם את ספירות ה-AI Agent של הלקוח (totalAgents, activeAgents, pausedAgents, draftAgents), והרמה העליונה מוסיפה את totalActiveAgents ו-totalPausedAgents עבור הדף. שדות הקמפיין מכסים קמפיינים קלאסיים בלבד. hasIssues / issueDetails מסמנים תתי-חשבונות ששווה לבדוק. בחשבון עם סוכנים, הם מגיעים מציון המוכנות של הסוכנים המופעלים (לדוגמה "WhatsApp Web is disconnected" או "Agent \"Front desk\": Routed on a channel that is not connected"); סוכנים כבויים לעולם אינם מסומנים. בחשבון ללא סוכנים, הם מסמנים קמפיינים קלאסיים, כגון קמפיין מושהה. השתמש בזה כדי לבנות לוח מחוונים לבדיקת תקינות עבור כל תיק הלקוחות במקום לפתוח כל לקוח כדי לראות אילו סוכנים כבויים.

עבור הודעות ופעילות אשראי לאורך זמן עבור כל לקוח (סדרה מוכנה לתרשים ולא תמונת מצב של רגע נתון), עיין ב-GET /analytics/agency-rollup במדריך ה-Analytics API.

שלח חשבון לקוח שכבר הוגדר #

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

תמונת מצב (snapshot) היא תבנית לשימוש חוזר: סוכן בינה מלאכותית אחד או יותר בתוספת בסיס הידע, הכלים והמדיה שלהם, שנלכדו מהחשבון שלך. שני נקודות קצה (endpoints) מכניסים אותה לתהליך ההקצאה שלך.

אוטומטי — כל לקוח חדש מקבל אותה מלידה. סמן תמונת מצב כברירת המחדל שלך פעם אחת, וכל חשבון שתצור מאותו רגע יגיע כשהיא מותקנת בו. זה מכסה חשבונות שנוצרו דרך POST /v1/subaccounts, חשבונות שאתה יוצר בלוח הבקרה, וחשבונות שנוצרים אוטומטית כאשר לקוח משלם דרך קישור התשלום שלך.

ראשית, מצא את מזהה (id) תמונת המצב:

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

לאחר מכן הגדר אותה כברירת מחדל:

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

זו כל האינטגרציה. שלח {"snapshot_id": null} כדי לכבות אותה שוב. באפשרותך לעשות את אותו הדבר מלוח הבקרה על ידי לחיצה על הכוכב בדף Snapshots.

כדי לקרוא מה מסומן כרגע בכוכב (למשל, לפני שסקריפט הקצאה מחליט אם להגדיר אחד), GET /v1/snapshots/default מחזיר { "success": true, "data": { "default_snapshot_id": "SNAPSHOT_ID" } } — null כאשר שום דבר אינו מסומן בכוכב. GET /v1/snapshots (משמש למציאת ה-id לעיל) מחזיר את אותו default_snapshot_id לצד מערך ה-snapshots המלא, כך שרוב האינטגרציות זקוקות רק לקריאה אחת. שדות אובייקט תמונת המצב המלאים נמצאים במדריך Snapshots.

לפי דרישה — התקנה בחשבון אחד. שימושי עבור קליטת לקוח קיים, או עבור מתן תבנית שנייה ללקוח במועד מאוחר יותר.

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

השמט את sub_account_id והיא תותקן בחשבון הסוכנות שלך במקום זאת. בדומה לנקודות הקצה /subaccounts, אלו מציינות את חשבון היעד בנתיב או בגוף הבקשה במקום דרך הפרמטר הסביבתי sub_account_id.

כדאי לדעת לפני שמתחילים לבנות על זה:

• סוכנים מותקנים מתחילים במצב מושהה. חבר תחילה את הערוצים של הלקוח, ולאחר מכן הפעל את הסוכן. זה נכון גם עבור הנתיב האוטומטי וגם עבור הנתיב לפי דרישה.
• הקצאה לעולם לא נכשלת בגלל תמונת מצב. אם ההתקנה לא יכולה להסתיים, חשבון הלקוח עדיין נוצר וניתן לשימוש — הוא פשוט מגיע ריק וניתן להחיל את תמונת המצב לאחר מכן.
• ערוצים, יומנים וחיבורי OAuth לעולם לא מועתקים. כל חשבון מחבר את שלו. כלים המשתמשים במפתח API פשוט ממשיכים לעבוד מיד.
• החלה פעמיים יוצרת עותק שני. שום דבר לא נדרס.

בניית התבנית עצמה באמצעות ה-API #

POST /v1/snapshots · סוכנים, פונקציות מותאמות אישית ומדיה באמצעות ה-API

הסעיף שלעיל מפיץ תמונת מצב (snapshot) שמישהו בנה בלוח הבקרה. גם חלק העריכה חשוף, כך שניתן להריץ את כל התהליך — הרכבת ההגדרה הראשית פעם אחת, לכידתה והעברתה לכל לקוח — מתוך קוד.

החלקים, לפי הסדר שבו סקריפט הקצאה משתמש בהם:

1. צרו את הפונקציות המותאמות אישית שלכם. POST /v1/custom-functions יוצרת אחת; GET /v1/custom-functions מציג את מה שיש לכם, ו-GET, PUT ו-DELETE ב-/v1/custom-functions/{customFunctionId} קוראים, מעדכנים ומסירים אחת. POST /v1/custom-functions/test מריץ בדיקה (dry-run) להגדרה לפני שמירתה.
2. צרו ועצבו את הסוכן. POST /v1/agents יוצר אותו, PUT /v1/agents/{agentId} מעדכן אותו, ו-PATCH /v1/agents/{agentId}/active עם { "active": false } שומר עליו במצב מושהה בזמן שאתם עובדים (אותה קריאה עם true מפעילה אותו). GET /v1/agents מציג אותם.
3. תנו לסוכן את היכולות שלו. POST /v1/agents/{agentId}/custom-functions עם { "custom_function_id": "..." } מצמיד פונקציה לסוכן; ה-DELETE /v1/agents/{agentId}/custom-functions/{customFunctionId} התואם מנתק אותה.
4. מלאו את ספריית המדיה. POST /v1/agents/{agentId}/media-library מעלה פריט (JSON עם base64Data, mimeType, title, description); GET מציג את הפריטים של הסוכן, ו-PATCH/DELETE ב-/{itemId} מעדכנים או מסירים אחד.
5. לכדו זאת כתמונת מצב (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
  }'

משם זה ממשיך לסעיף הקודם: סמנו אותו כברירת מחדל כך שכל לקוח חדש ייוולד איתו, או החילו אותו לפי דרישה. פעולות תחזוקה נמצאות לצד זה: PATCH /v1/snapshots/{snapshotId} עם { "name": "..." } משנה שם של תמונה, DELETE /v1/snapshots/{snapshotId} מוחק אחת (ומסיר את סימון ברירת המחדל אם היא הייתה כזו), ו-GET /v1/snapshots/apply-targets מציג כל חשבון שאליו ניתן להתקין.

נקודות הקצה של הסוכן, הפונקציה המותאמת אישית והמדיה מקבלות כולן את sub_account_id, כך שאותן קריאות יכולות גם לתחזק סוכן ישירות בתוך חשבון של לקוח אחד. קריאות תמונת מצב (snapshot) פועלות תמיד על חשבון הסוכנות שלכם — התבנית נשארת אצלכם. סכימות מלאות של בקשות ותגובות עבור כל אלו נמצאות ב-API Reference.

ניהול דרגות התמחור שלכם דרך ה-API #

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

ניתן לקרוא ולשנות את התוכניות שאתם מוכרים ב-SaaS Mode → Pricing Tiers מתוך הקוד, כך שפאנל הניהול או סקריפט ההקצאה שלכם יוכלו להוסיף תוכנית, לעדכן מחיר או לספק קישור לתשלום מבלי שאף אחד יצטרך לפתוח את לוח הבקרה. בצעו אימות עם מפתח ה-API של הסוכנות שלכם כמו בכל קריאה אחרת בדף זה; נקודות קצה אלו הן ברמת הסוכנות, ולכן הן אינן מקבלות sub_account_id. כל פעולת כתיבה מריצה את אותה אימות ואת אותו סנכרון מוצר ומחיר מול Stripe כמו בשמירה בלוח הבקרה, כך שתוכנית שנוצרה כאן אינה שונה מתוכנית שהגדרתם ידנית.

הצגת הדרגות שלכם #

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

תגובה

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

כל דרגה חוזרת עם ה-tierIndex שלה — המיקום שלה ברשימת התוכניות שלכם, שבאמצעותו שלוש הקריאות האחרות מתייחסות אליה — ועם checkout_url מוכן לשיתוף, אותו קישור שמופיע בלשונית Payments, המפנה כבר ל-דומיין ה-White Label שבו התוכנית נמכרת.

הוספת דרגה #

גוף הבקשה הוא אובייקט דרגה אחד; הוא מתווסף לסוף הרשימה שלכם.

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

התגובה מכילה את הדרגה שנוצרה, כולל ה-tierIndex שבו היא מוקמה וה-checkout_url שלה.

עריכת דרגה #

שלחו רק את השדות שברצונכם לשנות; כל שאר הפרטים בתוכנית יישארו כפי שהיו.

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

שדה שה-API אינו מזהה יסורב במקום להתעלם ממנו, והשגיאה תציין אותו בשמו — כך ששגיאת הקלדה לעולם לא תגרום לכתיבה שקטה של הגדרה שנראית פעילה אך אינה עושה דבר. שינוי המחיר, הזיכויים, המטבע או מחזור החיוב יוצר מחיר חדש ב-Stripe שלכם; לקוחות שכבר נרשמו יישארו במסלול שאליו נרשמו.

מחיקת דרגה #

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

אותו כלל כמו בלוח הבקרה: לא ניתן למחוק תוכנית שיש לה עדיין מנויים פעילים. הבקשה תחזור עם סירוב, ותציין כמה מנויים רשומים אליה — בטלו או העבירו אותם תחילה. מחיקה מוצלחת תחזיר בתגובה את הדרגות שנותרו לכם, כשהן ממוספרות מחדש.

השדות בדרגה #

שדות תקופת הניסיון משמעותיים רק בתוכנית שיש בה תקופת ניסיון: שמור שכבה (tier) עם trial_days: 0 והם יוסרו. מזהי המוצר והמחיר של Stripe עבור התוכנית מנוהלים עבורך ולא ניתן להגדירם ידנית.

שלושה דברים שחשוב להקפיד עליהם:

• אינדקסי שכבות (Tier indexes) הם מיקומים, לא מזהים קבועים. מחיקת תוכנית מזיזה כל תוכנית שאחריה מיקום אחד אחורה, לכן יש לאחזר מחדש את הרשימה לאחר כל שינוי — ולהעתיק מחדש את קישורי התשלום שפרסמת, בדיוק כפי שהיית עושה לאחר מחיקת תוכנית בלוח הבקרה.
• יש להגדיר תחילה את מצב SaaS. נקודות קצה אלו דורשות חשבון סוכנות עם מיתוג לבן (white labeling) ומפתח Stripe שכבר נשמר; ללא אלו, לא קיים חשבון Stripe שעליו יוכלו לשבת המוצר והמחיר של התוכנית.
• המכסה היא עשרים תוכניות, בדיוק כמו בלוח הבקרה. השדה max_tiers בתגובת הרשימה מציין את המגבלה הנוכחית.

סכימות הבקשה והתגובה המלאות נמצאות ב-API Reference, תחת Agency.

הגדר את המחיר לקרדיט דרך ה-API #

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

המחיר שלקוחות משלמים עבור רכישות מזדמנות (מצב SaaS ← תמחור לפי קרדיט) ניתן לקריאה ולשינוי גם מתוך הקוד. אפשרות זו נועדה למקרים שבהם המחיר צריך להשתנות באופן עצמאי: סוכנות שמוכרת קרדיטים במטבע אחד אך גובה תשלום במטבע אחר יכולה לתת למשימה מתוזמנת לעדכן את המחיר בהתאם לשינויי שער החליפין, במקום שמישהו יעדכן אותו ידנית מדי שבוע.

קריאת המחיר הנוכחי #

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

תגובה

{
  "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 הוא המחיר הנמוך ביותר שהפלטפורמה מאפשרת במטבע זה, כך שמשימה יכולה לבדוק מחיר חדש לפני שליחתו. כל שלושת הערכים הם null עד להגדרת מחיר.

שינוי המחיר #

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

שלח רק את מה שברצונך לשנות. price_per_credit_cents הוא המחיר ביחידת המטבע הקטנה ביותר (130 = R$1.30); currency הוא קוד ISO באותיות קטנות; note היא שורה אופציונלית של עד 200 תווים המוצגת ללקוחות ישירות מתחת למחיר לקרדיט בדף החיוב שלהם — שימושי למחיר ייחוס במטבע אחר, כגון “0.25 דולר ארה"ב לקרדיט לפי שער הייחוס שלנו”. שלח "note": "" כדי להסיר אותה. התגובה היא באותו מבנה כמו בקריאה לעיל, כך שמשימה יכולה להשוות ולדלג על הכתיבה כאשר דבר לא השתנה.

אותם כללים חלים כפי שחלים בלוח הבקרה: המחיר לא יכול לרדת מתחת למינימום של הפלטפורמה עבור אותו מטבע, והחשבון זקוק ל-White Labeling. בניגוד לנקודות הקצה של שכבות התמחור, אין צורך במפתח Stripe כדי לקרוא או לשנות ערך זה.

תן למשימה מפתח שלא יכול לעשות דבר אחר #

הזנת מפתח הסוכנות המלא שלך למתזמן מעניקה גישה רחבה יותר ממה שעדכון מחיר דורש. במקום זאת, צור מפתח מוגבל (scoped key) המוגבל לאזור מחיר קרדיט סוכנות: מפתח זה יכול לקרוא ולשנות את המחיר לכל קרדיט ותו לא — הוא אינו יכול לגשת לחשבונות משנה, תוכניות, קרדיטים או לחיבור ה-Stripe שלך.

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

התגובה נושאת את המפתח החדש ב-api_key פעם אחת בלבד — הוא לא יוצג שוב לעולם, לכן שמור אותו מיד. הגדר "read_only": true עבור מפתח שצריך רק לקרוא את המחיר, והוסף "expires_at" (תאריך בפורמט ISO) אם ברצונך שהוא יפסיק לעבוד מעצמו. רק המפתח של בעל החשבון יכול ליצור מפתחות מוגבלים; הצג או בטל אותם באמצעות GET /v1/api-keys ו-DELETE /v1/api-keys/{id}.

אפשר לתת-חשבון לקרוא את התמחור שלך #

GET /v1/subaccounts/agency-pricing

כל נקודת קצה אחרת בדף זה נקראת עם מפתח הסוכנות שלך, תוך מיקוד אופציונלי בלקוח באמצעות sub_account_id. זו פועלת הפוך: היא נקראת עם מפתח ה-API של תת-החשבון עצמו, ללא sub_account_id, כך שדף הטעינה של הלקוח (או אינטגרציה שאתה בונה עבורו) יכול להציג את מה שאתה גובה ממנו מבלי לראות לעולם את חשבון הסוכנות שלך.

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

תגובה

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

זה משקף בדיוק את מה ש-GET /v1/agency/pricing-tiers ו-GET /v1/agency/credit-price מחזירים עבורך כסוכנות, פחות כל מה שהלקוח לא צריך לראות (מזהי Stripe, max_tiers, וכן הלאה). זה עובד רק עבור חשבון שהוא אכן תת-חשבון עם סוכנות מקושרת — קריאה לזה מחשבון הסוכנות שלך תחזיר שגיאת הרשאה.

דברים שחשוב לזכור #

• השתמש במפתח הסוכנות שלך. בצע אימות לכל קריאה באמצעות מפתח ה-API של חשבון הסוכנות שלך — לא של חשבון המשנה. הפרמטר sub_account_id הוא זה שמפנה את הפעולה.
• הזיכויים מגיעים מחשבון המשנה. רכישות וחיובים חוזרים יורדים מיתרת הזיכוי של חשבון המשנה הממוקד, לא מהיתרה שלך.
• השגיאה 404 פירושה “לא חשבון המשנה שלך”. בדוק שוב את ה-id וודא שמדובר בחשבון שאתה מנהל.
• הפרמטר הוא אופציונלי בכל מקום שבו הוא מתקבל. אם תשמיט אותו, אותו endpoint יפעל על חשבון הסוכנות שלך, כך שתוכל לעשות שימוש חוזר באינטגרציה אחת עבור שניהם.

קשור #

• גישת API — אימות, כתובת בסיס, שגיאות, מגבלות קצב.
• חשבונות משנה — רשימה וניהול של החשבונות שאליהם ניתן לכוון.
• טעינה אוטומטית של חשבון משנה — הענקת קרדיטים לחשבון משנה באמצעות webhook + API.
• API של סוכני AI: יצירה והגדרה של סוכני AI.
• API של קמפיינים: משאב הקמפיינים הקלאסיים שיצא משימוש, כולל הפניה מלאה לשדות.
• API של חיבור ערוצים — חיבור הערוצים של הלקוח.
• API של נקודות כניסה: החלטה איזה סוכן יקבל שיחה חדשה.
• מדריך Analytics API (בסעיף ה-API) — ריכוז חשבונות משנה של סוכנות וכל נקודת קצה אחרת של דוחות.
• תמונות מצב (Snapshots) — מה תמונת מצב לוכדת וכיצד לבנות אחת בלוח הבקרה.