API für Agenturen #

Als Agentur können Sie dieselbe REST-API verwenden wie Ihre Kunden, jedoch einzelne Anfragen an eines Ihrer verwalteten Unterkonten anstatt an Ihr eigenes Konto richten. Dies ermöglicht es Ihnen, Tools zu entwickeln, die ein Onboarding für Kunden von Anfang bis Ende durchführen – das Erstellen ihrer KI-Agenten, das Trainieren ihrer KI auf einer Wissensdatenbank, das Importieren ihrer Kontakte, das Verbinden ihrer Messaging-Kanäle und das Kaufen von Telefonnummern – alles, ohne sich manuell bei jedem Unterkonto anmelden zu müssen.

Diese Seite behandelt nur das agenturspezifische Verhalten: wie man im Namen eines Unterkontos mit dem Parameter sub_account_id agiert. Für die Grundlagen (Generierung eines Schlüssels, Authentifizierung, Basis-URL, Fehlerformat, Ratenbegrenzungen) beginnen Sie mit dem Leitfaden zum API-Zugriff. Alles, was dort steht, gilt auch hier – Sie authentifizieren sich mit dem API-Schlüssel Ihres Agenturkontos.

Funktionsweise von „Im Namen von agieren“ #

Standardmäßig wirkt sich jede API-Anfrage auf das Konto aus, dem der API-Schlüssel gehört – Ihr Agenturkonto. Um stattdessen für ein verwaltetes Kundenkonto zu agieren, fügen Sie der Anfrage den optionalen Parameter sub_account_id hinzu und setzen Sie ihn auf die Konto-ID des Kunden.

• sub_account_id weglassen → die Anfrage wirkt sich auf Ihr eigenes Agenturkonto aus.
• sub_account_id einfügen → die Anfrage wirkt sich auf dieses Unterkonto aus, jedoch erst, nachdem die Plattform bestätigt hat, dass das Unterkonto tatsächlich Ihnen gehört.

Sie authentifizieren sich immer mit dem API-Schlüssel Ihres Agenturkontos. Sie benötigen niemals den eigenen Schlüssel des Unterkontos und müssen niemals die Anmeldedaten des Unterkontos verwalten.

Wo der Parameter platziert wird #

• GET- / DELETE-Endpunkte → übergeben Sie es als Abfrageparameter: ?sub_account_id=THE_SUB_ACCOUNT_ID (zusammen mit Ihrem apiKey, falls Sie sich per Abfrage authentifizieren).
• POST- / PUT- / PATCH-Endpunkte → fügen Sie es im JSON-Request-Body als "sub_account_id": "THE_SUB_ACCOUNT_ID" hinzu.
• KI-Assistenten → nichts zu konfigurieren. Der MCP-Server übernimmt dieselbe Einstellung für seine Tools, sodass eine Verbindung mit Ihrem Agenturschlüssel über jeden Kunden berichten kann: Nennen Sie den Kunden einfach in Ihrer Anfrage („Wie viele Kontakte hat Bella’s Bistro?“). Schreibaktionen sind ebenfalls verfügbar: Jeder Endpunkt, der sub_account_id akzeptiert, wird als Tool bereitgestellt, sodass Sie im Namen eines Kunden über dieselbe Verbindung erstellen, ändern und senden können.

Die ID eines Unterkontos finden #

Die sub_account_id ist die eindeutige ID des Kundenkontos. Sie erhalten die Liste Ihrer Unterkonten und deren IDs über die SubAccounts-API-Endpunkte (siehe den Leitfaden zu Unterkonten) oder über die Seite Unterkonten in der Seitenleiste.

Die Eigentümerschaft wird immer überprüft #

Wenn Sie eine sub_account_id übergeben, prüft die Plattform, ob es sich um ein echtes Unterkonto handelt und ob es zu Ihrer Agentur gehört. Erst dann wird die Anfrage ausgeführt.

Wenn die ID unbekannt ist, kein Unterkonto darstellt oder zu einer anderen Agentur gehört, schlägt die Anfrage mit einer 404-Antwort fehl:

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

Warum 404 und nicht 403? Eine „Forbidden“-Antwort würde einem Außenstehenden verraten, dass die ID existiert, ihm aber nicht gehört. Die Rückgabe desselben 404 für „existiert nicht“ und „gehört dir nicht“ bedeutet, dass der Endpunkt nicht dazu verwendet werden kann, herauszufinden, welche Konto-IDs zu anderen Agenturen gehören. Betrachten Sie ein 404 hier als „Dies ist kein Unterkonto, das Sie verwalten“.

Wo sub_account_id unterstützt wird #

sub_account_id wird im Grunde bei jedem Ressourcen-Endpunkt akzeptiert – bei jedem Aufruf, der kontoeigene Daten erstellt, liest, aktualisiert oder löscht. In der Praxis können Sie die gesamte Einrichtung eines Unterkontos mit Ihrem Agenturschlüssel bereitstellen und ausführen:

• KI-Einrichtung — Kampagnen, Agenten, FAQs, Wissensdatenbank-Quellen (Website-Crawl und Dokumenten-Upload), Wissensdatenbank-Gruppen, Broadcasts, benutzerdefinierte Funktionen, MCP-Server
• Kontakte & CRM — Kontakte (einschließlich Import), Listen, Tags, Aufgaben, Deals, Termine, Ereignisse
• Kanäle & Nummern — WhatsApp / WhatsApp Web / Telegram / Instagram & Messenger / LINE verbinden, Telefonnummern suchen / kaufen / verwalten, WhatsApp-Vorlagen, Kanal-Routing
• Messaging & Inhalte — Nachrichten senden, Chat-Sitzungen, Chat-Exporte, tägliche Zusammenfassungen
• Einstellungen & Integrationen — Webhooks, Chat-Widget-Konfiguration, White-Label-Konfiguration, BYOK-SMS und andere Kontoeinstellungen, Analysen, das Fehlerprotokoll

Bei jedem dieser Aufrufe ist der Parameter optional – lassen Sie ihn weg, und der Aufruf wird auf Ihrem eigenen Agenturkonto ausgeführt, sodass eine Integration für beides dient. Guthaben und Nutzung werden immer von dem Konto abgebucht, auf das Sie abzielen: Kosten für KI-Antworten, Nachrichten, Tags und Nummern eines Unterkontos belasten das Guthaben des Unterkontos.

Wo dies NICHT gilt #

Einige Endpunkte sind auf Agenturebene angesiedelt oder beziehen sich auf das eigene Konto und ignorieren sub_account_id:

• Verwaltung der Unterkonten selbst — die SubAccounts-Endpunkte (Unterkonto erstellen / auflisten / aktualisieren) und der BYOK-Endpunkt für Ausgabenlimits nennen das Unterkonto bereits in ihrem eigenen URL-Pfad. Die Preis- und Richtlinien-Endpunkte sowie die Chat-Überwachungs-Endpunkte folgen demselben Muster.
• Kopieren eines Agenten zwischen Konten — POST /v1/subaccounts/agents/copy benennt beide Konten selbst und nimmt das Ziel als targetUserId entgegen. Siehe das ausgearbeitete Beispiel unten. (Das ältere POST /v1/subaccounts/campaigns/copy funktioniert auf die gleiche Weise, ist aber zusammen mit dem Rest der Campaigns API veraltet.)
• Anpassen von Guthaben und die beiden agenturweiten Zusammenfassungen — POST /v1/subaccounts/credits identifiziert das Unterkonto stattdessen über email; GET /v1/subaccounts/credit-usage und GET /v1/subaccounts/campaign-status berichten über alle Unterkonten gleichzeitig, daher gibt es kein einzelnes Konto, auf das gezielt werden kann.
• Das eigene Konto Ihrer Agentur — API-Schlüsselverwaltung, Berichte zur Agenturnutzung, Teamverwaltung und Ihre Preisstufen beziehen sich immer auf Ihr Agenturkonto.
• Hinzufügen von Kontakten zu einer Liste oder Entfernen aus einer solchen: POST / DELETE /v1/contacts/lists und POST /v1/contacts/lists/batch beziehen sich auf das Konto, dem der Schlüssel gehört. Das Erstellen, Bearbeiten und Löschen der Listen selbst (/v1/lists) erfordert sub_account_id.
• Webhooks für eingehende Nachrichten — Endpunkte, an die externe Systeme etwas senden, sind an das Konto gebunden, dessen Anmeldedaten sie konfiguriert haben, daher gibt es nichts umzuleiten.

Die stets aktuelle, maschinenlesbare Liste der Parameter, die jeder Endpunkt akzeptiert, finden Sie in der API-Referenz Ihres Dashboards (Einstellungen → Integrationen → API-Schlüssel) sowie in der OpenAPI-Spezifikation unter GET /v1/docs/openapi.yaml. Wir veröffentlichen häufig API-Änderungen – betrachten Sie diese als die maßgebliche Informationsquelle.

Listen Sie Ihre Unterkonten auf oder überprüfen Sie eine E-Mail-Adresse #

GET /v1/subaccounts

Wird der Aufruf ohne Parameter getätigt, gibt er alle Unterkonten Ihrer Agentur in einem data-Array zurück. Fügen Sie den optionalen Abfrageparameter email hinzu, um einen einzelnen Kunden zu suchen:

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

• Diese E-Mail gehört zu einem Ihrer aktiven Unterkonten → HTTP 200, mit genau diesem Konto: { "success": true, "data": { ... } }.
• Dies ist nicht der Fall → HTTP 404, Agency Sub Account not found.

Es gibt keinen Parameter, der mit einem einfachen Ja oder Nein antwortet, lesen Sie daher den Statuscode: 200 bedeutet, dass die E-Mail zu einem Ihrer Kunden gehört, 404 bedeutet, dass dies nicht der Fall ist. Gelöschte Unterkonten werden nicht berücksichtigt, daher wird ein von Ihnen entferntes Konto ebenfalls als 404 angezeigt.

Jedes Konto wird mit seinem Profil, seinen Einstellungen, seinen Nutzungslimits und den aktivierten Funktionen zurückgegeben. Das ist alles, was Sie benötigen, um eine Kundenzeile in Ihrem eigenen Dashboard anzuzeigen.

Die Antwort enthält niemals Anmeldedaten. API-Schlüssel, Passwörter, Login-Token und die Details der Kanäle, die ein Kunde verbunden hat (Twilio, Google, Meta und „Bring-your-own-key“), werden entfernt, bevor die Antwort gesendet wird. Es gibt keinen Parameter zur Auswahl der zurückgegebenen Felder; lesen Sie daher die benötigten Felder aus und ignorieren Sie den Rest.

Erfordert API-Zugriff und ein Agenturkonto.

Ein Kundenkonto erstellen #

POST /v1/subaccounts

Das Erstellen des Kontos erfolgt über einen einzigen Aufruf mit der E-Mail-Adresse, dem Namen und dem Firmennamen des Kunden. Es gibt einige Dinge, die Sie wissen sollten, bevor Sie Ihren Registrierungsprozess darauf aufbauen.

Sie können das Passwort nicht wählen. Es gibt kein Passwortfeld: Eines wird für Sie generiert und einmalig als temporary_password in der 201-Antwort zurückgegeben. Speichern Sie es oder leiten Sie es sofort weiter, da es Ihnen später nicht mehr angezeigt wird. Der Kunde kann es über sein Profil ändern oder über den Anmeldebildschirm zurücksetzen.

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

Es wird nichts an den Kunden gesendet, es sei denn, Sie fordern es an. Standardmäßig wird das Konto im Hintergrund erstellt, und es ist Ihre Aufgabe, den Kunden darüber zu informieren. Senden Sie send_account_info_to_sub_account: true, und der Kunde erhält eine Willkommens-E-Mail mit seiner E-Mail-Adresse, dem temporären Passwort und einem Link zur Anmeldung – alles auf Ihrer eigenen White-Label-Domain und unter Ihrer Marke.

Das Flag betrifft nur die E-Mail des Kunden. Ihre Agentur erhält immer eine Benachrichtigung über ein neues Unterkonto erstellt, diese enthält jedoch niemals das Passwort: Aus Sicherheitsgründen erhalten Sie es ausschließlich in der 201-Antwort. Falls es verloren geht, legt der Kunde über Passwort vergessen auf dem Anmeldebildschirm ein eigenes fest.

Sie legen das Anfangsguthaben fest. usage_limits.credits ist das anfängliche Ausgabenlimit des Kunden und usage_limits.monthly_credits das wiederkehrende monatliche Guthaben. Senden Sie "credits": 0 und das Konto startet ohne verfügbares Guthaben; lassen Sie credits weg, startet es mit einem einmaligen Guthaben von 100 Credits, sodass die KI sofort antworten kann. Bei der Erstellung wird nichts aus Ihrem Agentur-Pool abgebucht: Ihr Pool wird erst belastet, wenn der Kunde die Credits tatsächlich verbraucht.

Firmennamen müssen innerhalb Ihrer Agentur eindeutig sein. Zwei Ihrer Kunden können nicht beide „Client Co“ heißen, da dieser Name das Konto in Ihrem Dashboard und Ihren Berichten identifiziert. Die Namen anderer Agenturen spielen dabei keine Rolle.

Wenn der Aufruf fehlschlägt:

Ein Kundenkonto löschen #

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

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

Dies entspricht der Löschen-Schaltfläche auf der Seite „Unterkonten“ und kann nicht rückgängig gemacht werden. Der Kunde wird sofort gesperrt und zählt nicht mehr zu Ihrer Gesamtzahl an Kunden; seine Unterhaltungen, Kontakte, Agenten und verbundenen Kanäle werden in den nächsten Minuten im Hintergrund gelöscht. Ein Plan, den der Kunde über Ihre Kaufabwicklung erworben hat, wird gekündigt.

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

• Übergeben Sie email oder uid. Wenn Sie beides übergeben, müssen sie denselben Client benennen.
• Nur Ihre eigenen Clients können gelöscht werden. Jede andere E-Mail-Adresse oder UID sowie ein bereits gelöschter Client führen zu 404.
• Ein erneuter Aufruf, während der Löschvorgang noch läuft, gibt 200 mit "status": "already_in_progress" zurück.
• KI-Assistenten, die über den MCP-Server verbunden sind, haben dies als delete_subaccount-Tool, wenn sie mit der Standard-MCP-Adresse verbunden sind (Agentur-Tools sind bei einer White-Label-MCP-Adresse ausgeschlossen).
• Um einen Client für eine Weile zu stoppen, ohne etwas zu verlieren, pausieren Sie ihn stattdessen: Er ist ausgesperrt, alles bleibt erhalten und ein Aufruf macht ihn wieder verfügbar.

Praxisbeispiel: Instagram & Messenger für ein Unterkonto verbinden #

Das Verbinden von Instagram & Messenger ist ein browserbasierter Ablauf. Sie starten ihn über die API, übergeben dem Kunden die zurückgegebene Einwilligungs-URL (oder öffnen sie für ihn), warten darauf, dass er die Autorisierung in seinem Browser vornimmt, und wählen dann die zu verbindende Seite aus – all dies, während Sie mit sub_account_id auf sein Unterkonto zielen.

Schritt 1 – Die Verbindung starten #

Rufen Sie den Connect-Endpunkt mit dem sub_account_id des Kunden im Body auf. Hier werden keine Anmeldedaten gesendet; die Plattform gibt eine Einwilligungs-URL zurück, die der Kunde in einem Browser öffnen muss, sowie ein einmaliges Korrelationstoken.

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

Antwort:

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

Leiten Sie den Kunden zur Autorisierung in einem Browser an oauth_url weiter. Das state_token korreliert diesen Versuch und ist ein kurzlebiges Geheimnis – protokollieren Sie es nicht. Der Versuch läuft bei expires_at ab; falls er abläuft, starten Sie erneut.

Schritt 2 – Abfragen, bis die Seiten geladen sind #

Nachdem der Client autorisiert hat, fragen Sie den Status-Endpunkt ab (mit demselben sub_account_id, diesmal als Abfrageparameter), bis die verbindbaren Seiten erscheinen.

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

Antwort:

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

Das Feld status durchläuft pending → token_received → pages_loaded → connected. Warten Sie auf pages_loaded, bevor Sie eine Seite auswählen. Anstatt fortzufahren, können auch zwei terminale Fehlerzustände auftreten: failed und expired (der Client hat die Zustimmung verweigert oder das ca. 30-minütige Zeitfenster des State-Tokens ist abgelaufen) — ein reason-Feld ist enthalten, wenn einer dieser Fehler auftritt. Beenden Sie das Polling und starten Sie bei Schritt 1 neu, falls einer dieser Fehler angezeigt wird; warten Sie nicht ewig auf pending. Seiten-Zugriffstoken werden niemals zurückgegeben.

Schritt 3 — Wählen Sie die zu verbindende Seite aus #

Wählen Sie eine der Seiten-IDs aus Schritt 2 aus. Durch die Auswahl einer Seite werden sowohl Instagram als auch Messenger für diese Seite verbunden. Fügen Sie sub_account_id erneut in den Body ein.

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

Antwort:

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

Das war’s – Instagram und Messenger sind jetzt mit dem Unterkonto des Clients verbunden. Sie haben lediglich das page_id bereitgestellt; die zugrunde liegende Berechtigung wird auf dem Server aufgelöst und niemals an Ihre Integration weitergegeben.

Praxisbeispiel: Eine Nummer für ein Unterkonto kaufen #

Der Kauf einer Nummer funktioniert auf die gleiche Weise: Suchen Sie mit sub_account_id in der Abfrage und kaufen Sie sie dann mit dem Wert im Body. Die Credits werden vom Guthaben des Unterkontos abgebucht und die Nummer wird für das Unterkonto bereitgestellt.

Suche (cURL):

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

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

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

Antwort:

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

Die Nummer wird im Status PURCHASED bereitgestellt und die Registrierung des WhatsApp-Absenders läuft im Hintergrund weiter. Pollen Sie GET /v1/phone-numbers/{phoneNumber}/status?sub_account_id=abc123def456, bis der Status ONLINE erreicht, bevor Sie Nachrichten senden.

Praktisches Beispiel: Einen Vorlagen-Agenten für jeden neuen Kunden bereitstellen #

Das übliche Agenturmodell besteht darin, einen Master-Agenten in Ihrem Agenturkonto zu führen, der genau so eingestellt ist, wie jeder Kunde starten soll, und bei der Bereitstellung eine Kopie davon in jedes neue Unterkonto zu übertragen. Das sind drei Aufrufe, und danach muss nichts mehr wiederholt werden: Die Kopie behält ihre Einstellungen bei, bis Sie sie ändern.

Schritt 1 — Den Agenten kopieren #

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

Die Antwort enthält die ID des neuen Agenten unter data.agent_id. Die FAQs, die Wissensdatenbank und die Medienbibliothek werden mit kopiert; die WhatsApp-Vorlagen, verknüpften Social-Media-Beiträge und Kontakte des Quellkontos werden bewusst nicht übernommen. Die vollständige Feldliste finden Sie in der AI Agents API.

Beachten Sie, dass dieser Endpunkt targetUserId anstelle von sub_account_id verwendet — er benennt beide Konten selbst. Die beiden folgenden Aufrufe verwenden den normalen sub_account_id-Parameter.

Schritt 2 — Einschalten #

Die Kopie kommt immer pausiert an, sodass sie niemanden benachrichtigen kann, bis Sie dies zulassen. Dies ist auch der richtige Zeitpunkt, um die KI-Stufe festzulegen, auf der sich der Kunde befinden soll; sie bleibt dort, sodass sie nicht nach einem Zeitplan erneut angewendet werden muss.

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

Um zu verhindern, dass der Kunde die Stufe nachträglich ändert, sperren Sie die zulässigen Stufen für das Unterkonto, anstatt den Wert erneut zu senden.

Schritt 3 — Die Kanäle des Kunden darauf ausrichten #

Die Kopie kommt auch ohne Routing an, sodass sie erst reagiert, wenn Sie sie als Antwortinstanz für die Kanäle festlegen, die der Kunde verbunden hat. Ein Aufruf pro Kanal:

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

Von hier an wird eine erste Nachricht von einem unbekannten Kontakt auf diesem Kanal automatisch vom kopierten Agenten empfangen. Siehe Einen Kanal auf einen Agenten ausrichten für die anderen Kanäle und das Routing pro Nummer.

Legen Sie die Zeitzone des Kunden fest, wenn Sie das Unterkonto erstellen. Übergeben Sie time_zone_id an POST /v1/subaccounts. Die aktiven Stunden eines Agenten werden in der Zeitzone des Unterkontos ausgewertet. Wenn ein Kunde ohne Zeitzone erstellt wird, wird sein Zeitplan gegen UTC gelesen – was sich unbemerkt darauf auswirkt, wann der Assistent antworten darf.

Überspringen des Einrichtungsassistenten für einen Kunden, den Sie selbst konfigurieren #

POST /v1/subaccounts

Standardmäßig wird der Besitzer eines neuen Unterkontos bei der ersten Anmeldung durch den geführten Einrichtungsassistenten (Setup Wizard) geleitet. Für „Done-for-you“-Kunden – bei denen Sie den KI-Agenten erstellen und die Kanäle verbinden, bevor sich der Kunde jemals anmeldet – übergeben Sie guided_onboarding: false, wenn Sie das Konto erstellen. Sie landen stattdessen auf dem normalen Startbildschirm – dem Dashboard auf einem Computer, ihren Chats auf einem Telefon – und der Eintrag für den Einrichtungsassistenten wird in ihrer Seitenleiste ausgeblendet.

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

Lassen Sie das Feld weg (oder senden Sie true) und der Assistent verhält sich genau wie immer, sodass bestehende Integrationen keine Änderungen benötigen. Um einem Kunden den Assistenten später wieder zur Verfügung zu stellen, zeigen Sie das Element guided_onboarding wieder mit PUT /v1/subaccounts/{subAccountUid}/menu-visibility (unten) an — die Menüsichtbarkeit steuert, ob der Assistent erreichbar ist, guided_onboarding steuert nur die Weiterleitung bei der ersten Anmeldung.

Aufgaben, tägliche Zusammenfassungen oder die Medienbibliothek für einen Kunden deaktivieren #

POST /v1/subaccounts

Diese drei Funktionen sind für jeden neuen Kunden aktiviert, sofern Sie nichts anderes angeben, und sie verhalten sich anders als alle anderen Funktionen in diesem Leitfaden: Sie sind Opt-out-Funktionen, keine Opt-in-Funktionen. Sie einfach aus features wegzulassen, reicht nicht aus, da die features-Liste einer älteren Integration sie schlichtweg nie erwähnte – wir können nicht unterscheiden, ob “die Agentur dies deaktiviert hat” oder “diese Liste geschrieben wurde, bevor die Option existierte”.

Geben Sie es daher explizit mit feature_settings an:

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

Jeder Schlüssel ist optional; alles, was Sie weglassen, bleibt aktiviert. Mit tasks: false hört die KI auf, Aufgaben für diesen Kunden zu erstellen, und es werden keine “Neue Aufgabe erstellt”-E-Mails versendet; mit daily_summaries: false wird die nächtliche Zusammenfassung weder generiert noch per E-Mail verschickt.

feature_settings ist das Einzige, was diese drei Funktionen bei der Erstellung deaktiviert. Sie aus features wegzulassen, bewirkt für sich genommen nichts, egal wie der Rest Ihrer Liste aussieht – das ist beabsichtigt, damit eine ältere Integration nicht stillschweigend alle drei verliert.

Um dies nachträglich zu ändern, senden Sie die vollständige features-Liste an PUT /v1/subaccounts/{subAccountUid}/features – dort schaltet das Vorhandensein in der Liste eine Funktion ein und das Fehlen schaltet sie aus.

Automatische Anmeldung Ihrer Kunden in deren Unterkonto (SSO) #

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

Ein einziger Aufruf mit Ihrem Agentur-API-Schlüssel liefert eine sofort einsatzbereite URL, die den Kunden direkt in seinem eigenen Unterkonto anmeldet – ohne Anmeldebildschirm, ohne Passwortabfrage, ohne dass Sie etwas zusätzlich entwickeln müssen. Öffnen Sie diese in einem neuen Tab, per Weiterleitung oder in einem iframe innerhalb Ihres eigenen Produkts.

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

Antwort

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

So nutzen Sie es optimal:

• Ein Sprung. Das Öffnen von url meldet den Kunden an und führt ihn direkt auf die redirect-Seite des Dashboards – ohne Anmeldebildschirm oder Zwischenseite. deep_link_url benennt dasselbe Ziel für Integratoren, die es bevorzugen, nach der Anmeldung explizit zu einem Frame zu navigieren; sobald die Sitzung besteht, funktioniert jeder Dashboard-Pfad in diesem Browser-Kontext.
• Bei Bedarf erstellen, sofort öffnen. Der Link enthält ein Anmelde-Credential und läuft nach etwa einer Stunde ab. Fordern Sie ihn serverseitig in dem Moment an, in dem der Kunde klickt, und speichern oder versenden Sie ihn niemals per E-Mail.
• Das Anmelde-Token wird im URL-Fragment (#…) übertragen, das Browser niemals an Server senden, und es wird aus der Adressleiste entfernt, sobald es verbraucht wurde.
• Nur Ihre eigenen Unterkonten. Der Endpunkt lehnt jedes Konto ab, das nicht Ihrer Agentur gehört.
• Ein abgelaufener Link zeigt einen klaren Fehler mit einem Pfad für einen erneuten Versuch an – erstellen Sie einfach einen neuen.

Navigationselemente in einem Unterkonto ausblenden #

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

Steuert, welche Seitenleisten- und Einstellungsoptionen ein Unterkonto sieht – nützlich, wenn Sie das Dashboard einbetten und nur die Bereiche anzeigen möchten, die Ihr Produkt noch nicht abdeckt. Alles, was nicht aufgeführt ist, bleibt sichtbar; senden Sie null als gesamten menuVisibility-Wert, um alles wieder auf sichtbar zurückzusetzen. Das Ausblenden eines Elements verbirgt den Menüeintrag – kombinieren Sie dies mit den Funktionen, die Sie dem Unterkonto gewähren, um den Zugriff strikt zu regeln.

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

Antwort

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

side_nav akzeptiert diese 13 Schlüssel, die den Namen der Seitenleistenelemente entsprechen: Dashboard, DailySummaries, Chats, Contacts, Deals, Tasks, Automations, Campaigns, Appointments, Settings, Help, CreditsCounter (das in der Seitenleiste angezeigte Guthaben) und guided_onboarding (der Einrichtungsassistent). Campaigns blendet nur die veraltete Kampagnenseite aus; die Seiten KI-Agenten und Broadcasts haben keinen Schlüssel und können auf diese Weise nicht ausgeblendet werden. Drei weitere Schlüssel – AiInsights, Sub Accounts und Agency Reselling – werden akzeptiert, bewirken aber nichts: Sie galten nur für das veraltete klassische Dashboard, daher hat ihre Einstellung keine Auswirkungen auf Ihre Unterkonten. Fehlende Schlüssel bedeuten, dass sie sichtbar sind; wenn Sie sich selbst beim Unterkonto anmelden, werden ausgeblendete Elemente vorübergehend angezeigt, damit Sie die Einstellungen jederzeit rückgängig machen können.

Dasselbe menuVisibility-Objekt akzeptiert auch zwei optionale Felder für das Haupt-Dashboard des Clients. dashboard_widgets ordnet eine Widget-ID true (angezeigt) oder false (ausgeblendet) zu, und dashboard_order ist eine Liste von Widget-IDs in der Reihenfolge, in der sie erscheinen sollen. Die IDs sind in ihrer Standardreihenfolge kpis, performance, credits (Guthabennutzung), funnel, inbox, outcomes, channel_health, ai_cost, ai_human, heatmap (Aktivste Zeiten), top_campaigns (Top-Agenten), contacts_by_country, activity und tasks_deals. Fehlende IDs bleiben sichtbar, und IDs, die in dashboard_order weggelassen wurden, folgen in der Standardreihenfolge. Zum Beispiel blendet "dashboard_widgets": { "credits": false } das Guthaben-Panel für den Client aus.

Das Ausblenden einer Seite aus dem Menü gewährt niemals Zugriff darauf. Automations erfordert, dass die Funktion automations für das Unterkonto gewährt wurde – setzen Sie den Schlüssel auf true, ohne dass dies der Fall ist, wird die Seite dennoch nicht angezeigt. Tasks und DailySummaries funktionieren genau umgekehrt: Sie sind für jeden Kunden aktiviert, es sei denn, Sie schalten sie aus (siehe Aufgaben, tägliche Zusammenfassungen oder die Medienbibliothek für einen Kunden deaktivieren).

Wählen Sie aus, welche Kanaltypen ein Client verbinden kann #

PUT /v1/subaccounts/{subAccountUid}/features

Die Kanaltypen-Schalter, die Sie auf einer Planebene sehen, sind gewöhnliche Feature-IDs. Sie können diese also pro Client über die API anstatt über das Dashboard festlegen. Dies ist einer der Endpunkte, der das Unterkonto in seiner eigenen URL benennt, daher benötigt er kein 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"
    ]
  }'

Worauf Sie achten sollten:

• Der Aufruf ersetzt die gesamte Funktionsliste. Senden Sie jede Funktion, die der Kunde behalten soll, nicht nur die, die Sie ändern. Dieselben IDs funktionieren als features auf POST /v1/subaccounts, wenn Sie das Konto erstellen.
• Kanaltypen und Kanalanzahl sind separate Schranken, und beide gelten. channels_1 / channels_3 / channels_unlimited steuern wie viele Verbindungen; die channel_* IDs steuern welche Typen. Das obige Beispiel bedeutet “bis zu 3 Verbindungen, und nur Chat-Widget, WhatsApp Web oder Instagram”.
• automations_edit, broadcasts_send und smart_lists_create erlauben es dem Kunden, eigene Automatisierungen, Broadcasts und intelligente Listen zu erstellen, zu bearbeiten und zu löschen. Eine Liste, die keine der drei nennt, belässt sie so, wie sie sind (bei einem neuen Unterkonto: alle drei an), sodass eine ältere Integration weiterhin funktioniert. Nennen Sie mindestens eine, und die Liste setzt alle drei: die, die Sie weglassen, werden ausgeschaltet. Der Kunde kann in jedem Fall weiterhin nutzen, was Sie für ihn eingerichtet haben, und Ihr Agentur-API-Schlüssel sowie Ihre eigenen Sitzungen im Konto des Kunden werden durch diese drei niemals eingeschränkt.
• Jede andere Funktion entspricht genau dem, was in der Liste steht, beim Erstellen und beim Aktualisieren. Ein Kunde, der mit einer features Liste erstellt oder aktualisiert wurde, erhält diese Funktionen und nichts anderes. Das beinhaltet crm_erp_integrations (den Bereich CRM & ERP-Integrationen, in dem ein Kunde Odoo verbindet): Er ist nur aktiv, wenn Ihre Liste ihn enthält; fügen Sie ihn also hinzu, wenn der Kunde ein CRM oder ERP verbinden soll. Ein Kunde, der ohne eine features Liste erstellt wurde, erhält das Standard-Set, das dies beinhaltet.
• Das Senden von gar keinen channel_* IDs bedeutet keine Kanaleinschränkung. Das ist das ursprüngliche Verhalten, weshalb bestehende Kunden nicht betroffen waren, als dies eingeführt wurde. Senden Sie eine oder mehrere, und alles andere wird auf der Kanalseite des Kunden als gesperrt mit einem Upgrade-Hinweis anstelle einer Verbinden-Schaltfläche angezeigt. Kanäle, die der Kunde bereits verbunden hat, funktionieren weiterhin.

Das Festlegen der Kanalliste auf einer Planebene, sodass jeder Client, der diese Ebene kauft, sie erbt, erfolgt im Dashboard unter Ihren Agentur-Planeinstellungen. Dieser Endpunkt legt sie für ein spezifisches Unterkonto fest.

Legen Sie ein exaktes Limit für Teammitglieder eines Kunden fest #

PUT /v1/subaccounts/{subAccountUid}/limits

Die team_seats_*-Funktionen bieten nur voreingestellte Stufen (3 / 5 / 10 / unbegrenzt). Um einem Kunden eine exakte Anzahl an Team-Plätzen zuzuweisen – 2, 7, 15 oder eine beliebige andere Zahl –, legen Sie stattdessen usage_limits.team_seats_limit fest. Diese Einstellung hat Vorrang vor den Voreinstellungen und wird von der Plattform bei jeder Einladung, jedem direkten Hinzufügen und jeder Einladungsannahme durchgesetzt: Sobald das Limit erreicht ist, werden weitere Einladungen serverseitig abgelehnt.

• Eine positive Ganzzahl ist das exakte Limit.
• 0 bedeutet, dass Teammitglieder nicht enthalten sind – der Kunde kann niemanden einladen.
• -1 bedeutet unbegrenzt.
• null löscht das benutzerdefinierte Limit und greift auf die team_seats_*-Voreinstellung zurück, die in der Funktionsliste festgelegt ist.

Das Senken des Limits entfernt niemals bestehende Teammitglieder; es verhindert lediglich das Hinzufügen neuer Mitglieder.

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

Sie können dies auch bei der Erstellung festlegen: POST /v1/subaccounts akzeptiert usage_limits.team_seats_limit mit derselben Semantik. Um den aktuellen Wert zu lesen, rufen Sie das Unterkonto mit GET /v1/subaccounts?email=... ab und prüfen Sie usage_limits.team_seats_limit (nicht vorhanden/null = die Voreinstellungen entscheiden). Derselbe Endpunkt aktualisiert auch credits, monthly_credits, roll_over_to_next_month, rollover_cap_months, rollover_expiry_days und byok_monthly_limit_usd — senden Sie nur die Schlüssel, die Sie ändern möchten. Ein creditManagementMode auf oberster Ebene ("manual" oder "reselling") schaltet den Kreditmodus des Clients um; ein über die API erstelltes Unterkonto startet im manuellen Modus. Schalten Sie es daher auf "reselling" um, bevor der Client über Ihren SaaS-Modus-Checkout bezahlt (siehe Unterkonten, Ausführen einer kostenlosen Testversion).

Wie sich dies auf die Sitzplatzbeschränkungen von SaaS-Plänen auswirkt. Ihre SaaS-Pläne können über ein eigenes Sitzplatzkontingent verfügen (festgelegt im Plan-Editor – siehe Team-Sitzplätze in einem Plan), das automatisch angewendet wird, wenn ein Kunde ein Abonnement abschließt. Ein Limit, das Sie über diesen Endpunkt festlegen, zählt als manuelle Zuweisung: Der Kauf eines Plans ersetzt diese durch das eigene Sitzplatzkontingent des Plans (da dieser Kauf eine explizite Entscheidung für einen Plan darstellt), aber unbeaufsichtigte monatliche Verlängerungen überschreiben niemals ein manuelles Limit – eine einmalige Ausnahme, die Sie einem Kunden gewähren, bleibt also über dessen Abrechnungszyklus hinweg bestehen. Das Löschen des manuellen Limits mit null übergibt die Kontrolle bei der nächsten Verlängerung wieder an den Plan.

Begrenzen Sie, was ein Kunde zwischen Verlängerungen mitnimmt. Zwei weitere usage_limits-Schlüssel befinden sich neben roll_over_to_next_month. Beide werden auch von POST /v1/subaccounts zum Zeitpunkt der Erstellung akzeptiert, und null löscht beide.

Wenn sie nicht festgelegt sind, greifen beide auf den Plan des Kunden zurück; ein hier gesendeter Wert hat Vorrang vor dem des Plans. Nur wiederkehrende Credits (das monatliche Guthaben und Plan-Credits) unterliegen diesen: Aufladungen, automatische Aufladungen und einmalige Hinzufügungen werden niemals begrenzt oder laufen ab. Jede Kürzung wird als Rollover-Kürzung-Guthabenanpassung oder Abgelaufene-Credits-Guthabenanpassung in den Guthabenverlauf des Kunden geschrieben und zählt niemals als Verbrauch. Die Entsprechungen auf Planebene sind rollover_cap_months und rollover_expiry_days in einer Preisstufe – siehe Die Felder einer Stufe und Begrenzung der Übertragung.

KI-Preise und -Richtlinien pro Kunde festlegen #

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

Acht weitere Schalter pro Kunde, zusätzlich zu /limits, /features und /menu-visibility oben. Jeder verwendet die UID des Unterkontos in der URL (kein sub_account_id Body-/Query-Parameter – das Ziel ist bereits im Pfad benannt) und ist auf die gleiche Weise begrenzt: Ihr Agenturschlüssel, und das Unterkonto muss zu Ihrer Agentur gehören.

Welche KI-Modelle ein Kunde verwenden kann

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 } meldet den Kunden für die Max AI-Stufe (oder davon ab) zum Listenpreis der Plattform an. Wenn Sie dies für einen BYOK-Kunden aktivieren, ändert sich dessen KI-Kostenmodell von „0 Credits, Zahlung über eigenen Schlüssel“ zu „Belastung des Credit-Pools“. Es handelt sich also um eine bewusste Entscheidung pro Kunde und nicht um eine agenturweite Standardeinstellung.

Um einzuschränken, AUS WELCHEN Stufen ein Kunde seine Agenten überhaupt auswählen darf (anstatt nur Max zu begrenzen), verwenden Sie 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 ist ein Array, das aus standard, economy, max, mini stammt — es ERSETZT die Allow-List des Kunden. Senden Sie null (oder []), um die Einschränkung aufzuheben und dem Kunden die Wahl einer beliebigen Stufe zu ermöglichen. Eine hier festgelegte Liste gilt als manuell gesetzte Sperre: Die allowed_ai_tiers eines Plans (siehe Verwalten Ihrer Preisstufen über die API) hat bei der Verlängerung keinen Einfluss mehr auf diesen Kunden. Dies ist wichtig, da ein Unterkonto, das seine eigene KI-Stufe wählt, Ihr Guthaben verbraucht. Es ist also das Steuerelement, um festzulegen, welche Modelle ein Reseller-Kunde auf Ihre Kosten nutzen darf.

Eine Antwortnachricht, während der Kunde kein Guthaben mehr hat

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

Wenn das Guthaben des Kunden (oder Ihr Pool) leer ist, kann die KI nicht antworten und der Kontakt hört nichts. Mit enabled: true erhält jeder Kontakt, der während des Ausfalls schreibt, einmalig message (max. 500 Zeichen, wird auf jedem Kanal unverändert gesendet), und die KI beantwortet diese Konversationen tatsächlich, sobald wieder Guthaben vorhanden ist. enabled: false speichert den Text für später; enabled: false ohne message entfernt die Einstellung. Derselbe Schalter wie Antwortnachricht bei fehlendem Guthaben im Bearbeitungs-Modal des Unterkontos – siehe Eine Antwortnachricht, während ein Kunde kein Guthaben mehr hat.

Was ein Kunde pro KI-Aktion zahlt und der WhatsApp-Gebührenaufschlag

Zwei Möglichkeiten, Ihren kundenseitigen Tarif festzulegen, von einfach bis detailliert:

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 ist der Preis in Credits, den das EIGENE Guthaben des Unterkontos pro Max-Modell-KI-Aktion verbraucht — Ihr kundenseitiger Aufschlag auf das, was Ihr Pool tatsächlich zahlt. null setzt die Überschreibung auf den Listenpreis der Plattform zurück. Der Satz muss mindestens so hoch sein wie die Kosten einer Max-Aktion für Ihren eigenen Pool (damit Sie einen Kunden niemals unter Ihren Kosten bepreisen können) und darf maximal 10 Credits betragen; eine Anfrage außerhalb dieses Fensters wird mit dem berechneten Mindestwert in der Fehlermeldung abgelehnt.

Für eine Preisgestaltung pro Aktionstyp anstelle eines pauschalen Max-Satzes verwenden Sie 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 ist eine ZUSAMMENFÜHRUNG mit der bestehenden Zuordnung des Kunden — ein Schlüssel, den Sie nicht erwähnen, bleibt wie er war, und null setzt diesen Schlüssel auf seinen Standardwert zurück. Die erkannten Schlüssel:

Die Raten pro Aktion müssen eine Zahl größer als 0 und bis zu 10 sein; wa_carrier_multiplier muss mindestens 1 betragen (kein Rabatt unter den Kosten) und darf maximal 10 sein. Das Senden eines nicht erkannten Schlüssels oder eines Wertes außerhalb des Bereichs führt zur Ablehnung der GESAMTEN Anfrage und benennt jeden fehlerhaften Schlüssel, sodass ein Tippfehler niemals stillschweigend einen Preis speichern kann, der eigentlich nicht angewendet wird.

Wenn Sie Mitglied im Champions Circle sind, überträgt insider-rate Ihren Insider-Tarif (20 % Rabatt auf Max- und Mini-Aktionen, Lead Finder-Leads und Automatisierungen) auf einen Kunden, anstatt ihn agenturweit anzuwenden:

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

Das Aktivieren erfordert, dass Ihr eigenes Agenturkonto tatsächlich eine Circle-Mitgliedschaft besitzt; das Deaktivieren ist jederzeit möglich, sodass ein Mitglied, dessen Status abgelaufen ist, die Einstellungen für einen Kunden jederzeit zurücksetzen kann.

Abschnitte des Playbooks eines Kunden sperren

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 ist ein Array, das aus instructions, goal, rules, personality, conclude_unless stammt — es ERSETZT die gesperrte Liste des Kunden. Ein gesperrter Abschnitt wird serverseitig abgelehnt, wenn das UNTERKONTO selbst versucht, ihn zu ändern (direkt oder per API-Schlüssel), während Sie (über sub_account_id) und die Dashboard-Admin-Ansicht des Kunden weiterhin alles bearbeiten können. Senden Sie null (oder []), um alles zu entsperren. Nützlich für „Done-for-you“-Kunden, bei denen Sie das Playbook besitzen und nach dem Ergebnis beurteilt werden.

Benachrichtigungseinstellungen eines Kunden in dessen Namen festlegen

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

Nur die Kategorien, die Sie senden, werden geändert: Jede wird mit der aktuellen Einstellung des Clients zusammengeführt, und jede Kategorie, die Sie weglassen, behält ihren Wert. Jede Kategorie unter settings akzeptiert enabled (boolean) und bis zu drei channels aus email, in_app, webhook. Senden Sie null, um die Plattform-Standardeinstellungen wiederherzustellen.

Alle sieben Endpunkte antworten mit { "success": true, "data": { "subAccountUid": "...", ...the field(s) you set... } } und werden mit dem Vorher-/Nachher-Wert protokolliert. Häufige Fehler: 403, wenn Ihr Konto kein Agentur-/Entwicklerkonto ist oder das Unterkonto nicht von Ihnen verwaltet wird, 400, wenn es sich nicht um ein Agentur-Unterkonto handelt oder ein Wert außerhalb des zulässigen Bereichs liegt.

Einen Kunden pausieren, der sein Abonnement ausgesetzt hat #

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

Wenn ein Kunde sein Abonnement bei Ihnen aussetzt, pausieren Sie sein Konto, anstatt es zu löschen: Alles, was er sendet, stoppt sofort – ausgehende Nachrichten, Broadcasts, KI-Antworten auf jedem Kanal – und wenn er sich anmeldet, sieht er eine bildschirmfüllende Konto pausiert-Sperre (mit Ihrer optionalen Nachricht) anstelle der App. Nichts wird gelöscht oder getrennt: Agenten, Broadcasts, verbundene Kanäle, Kontakte und Chatverlauf bleiben genau so, wie sie sind, sodass das Aufheben der Pause den Kunden genau dorthin zurückbringt, wo er aufgehört hat – ohne dass eine erneute Einrichtung erforderlich ist.

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

Antwort

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

Wenn der Kunde zurückkehrt, hebt POST /v1/subaccounts/SUB_ACCOUNT_UID/unpause (kein Body) die Sperre auf — das Senden und die KI-Antworten werden sofort wieder aufgenommen.

Wissenswertes:

• Dies entspricht dem Status des Schalters „Hard blocked“ im Dashboard (Sperren / Pausieren eines Unterkontos) – ein über die API pausierter Client wird im Dashboard als gesperrt angezeigt und umgekehrt; das Aufheben der Pause löscht eine von beiden Seiten gesetzte Sperre. Der aktuelle Status kann über das Feld agency_block unter GET /v1/subaccounts (level von "none", "soft_blocked" oder "hard_blocked") ausgelesen werden.
• Beide Aufrufe sind idempotent. Das Pausieren eines bereits pausierten Clients aktualisiert lediglich die Nachricht, den Grund und den Zeitstempel; das Aufheben der Pause bei einem aktiven Client ändert nichts.
• Der Client wird nicht automatisch per E-Mail benachrichtigt – viele Agenturen nutzen White-Labeling, daher bleibt es Ihnen überlassen, den Client zu informieren.
• Ihre eigene DM Champ-Abrechnung bleibt unberührt. Das Pausieren eines Clients wirkt sich nur auf Ihre Beziehung zu ihm aus.
• KI-Assistenten können dies ebenfalls tun: Der MCP-Server stellt diese Endpunkte als pause_subaccount- und unpause_subaccount-Tools unter der Standard-MCP-Adresse bereit (Agentur-Tools sind bei einer White-Label-MCP-Adresse ausgeschlossen).

Credits direkt gewähren oder abziehen #

POST /v1/subaccounts/credits

Fügt dem Guthaben eines Unterkontos einen exakten Betrag hinzu oder entfernt ihn – das API-Äquivalent zur manuellen Guthabenanpassung im Dashboard. Dies ist eine einmalige Guthabenänderung, die sich von den wiederkehrenden Einstellungen monthly_credits, roll_over_to_next_month, rollover_cap_months und rollover_expiry_days auf PUT /v1/subaccounts/{subAccountUid}/limits unterscheidet.

Dies ist der einzige Endpunkt auf dieser Seite, der das Unterkonto über die E-Mail-Adresse anstelle von sub_account_id identifiziert.

Sicheres Wiederholen. Senden Sie denselben Idempotenz-Schlüssel, wenn Sie einen Aufruf wiederholen, zum Beispiel nach einem Timeout, damit die Credits nur einmal hinzugefügt oder entfernt werden. Für 24 Stunden gibt eine Wiederholung mit demselben Schlüssel und denselben Details erneut die erste Antwort zurück (mit einem Idempotent-Replayed: true-Header), anstatt das Guthaben ein zweites Mal zu ändern. Derselbe Schlüssel mit einer anderen E-Mail-Adresse, einem anderen Betrag oder einer anderen Beschreibung wird abgelehnt (422), und eine Wiederholung, die eintrifft, während der erste Aufruf noch läuft, erhält einen 409-Fehler: Warten Sie einen Moment und versuchen Sie es erneut. Aufrufe ohne Schlüssel funktionieren wie bisher.

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

Antwort

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

Ein negativer amount, der den Kontostand unter Null bringen würde, wird mit 400 abgelehnt, wobei Ihnen das verfügbare Guthaben und der Betrag, den Sie abziehen wollten, mitgeteilt werden. Wenn sich der Kunde im Reselling-Modus befindet, zählt ein hinzugefügter Betrag als von ihm gekaufte Credits: Er wird in diesem Moment von Ihrem Agentur-Credit-Pool abgezogen, genau wie bei einem Kauf über Ihren Checkout, und bleibt nach dem nächsten monatlichen Reset genauso erhalten wie eine echte Aufladung. Wenn Ihr Pool den Betrag nicht decken kann, wird der Aufruf mit 402 abgelehnt und es ändert sich nichts. Laden Sie also zuerst Ihr Agenturguthaben auf. Ein Abzug bei einem Reselling-Kunden entfernt die Credits nur vom Kunden; es wird nichts an Ihren Pool zurückgegeben. Bei einem Standard-Kunden mit zugewiesenem Kontingent wird eine Hinzufügung stattdessen als Teil seines wiederkehrenden Kontingents behandelt und beansprucht nichts aus Ihrem Pool, bis der Kunde es ausgibt. In jedem Fall handelt es sich um eine einmalige Hinzufügung, daher werden sie durch ein Roll-over-Limit oder ein Ablaufdatum für das Konto (oder dessen Plan) niemals gekürzt – nur das wiederkehrende Kontingent und die Plan-Credits unterliegen diesen.

Unterhaltungen eines Unterkontos lesen #

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

Ermöglicht es Ihnen, eine Überwachungs- oder Support-Ansicht der Unterhaltungen eines Kunden zu erstellen, ohne sich in dessen Konto anzumelden. Listen Sie zuerst die Kontakte mit einer Vorschau der neuesten Nachricht auf und lesen Sie dann den vollständigen Nachrichtenverlauf eines Kontakts.

Kontakte auflisten

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

Antwort

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

Die Kontakte sind nach der letzten Aktivität sortiert. Blättern Sie weiter mit lastActivityAt, solange hasMore den Wert true hat.

Nachrichten eines Kontakts lesen

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

Antwort

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

Die Nachrichten werden beginnend mit der neuesten zurückgegeben; blättern Sie mit beforeTimestamp rückwärts durch den Verlauf.

Kreditverbrauch und Kampagnenstatus für Ihr gesamtes Portfolio lesen #

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

Zwei Dashboard-ähnliche Zusammenfassungen für jedes von Ihnen verwaltete Unterkonto, um Ihre eigenen Agenturberichte zu erstellen, anstatt jeden Kunden einzeln aufrufen zu müssen.

Kreditverbrauch

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

Übergeben Sie subAccountId, und die Antwort enthält zusätzlich records: einzelne Belastungen mit amount, reason, campaignName, contactName und timestamp. Bei einem Kunden, der seinen eigenen BYOK-Schlüssel anstelle Ihrer Kredite verwendet, werden die Kosten-/Token-Zahlen zurückgehalten (costsRedacted: true) – das ist Telemetrie zu Plattformkosten, die nicht für einen Reseller-Betrachter bestimmt ist.

Kampagnenstatus

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

Jede Zeile enthält außerdem die Anzahl der KI-Agenten des Kunden (totalAgents, activeAgents, pausedAgents, draftAgents), und die oberste Ebene fügt totalActiveAgents und totalPausedAgents für die Seite hinzu. Die Kampagnenfelder decken nur klassische Kampagnen ab. hasIssues / issueDetails markieren Unterkonten, die einen Blick wert sind. Bei einem Konto mit Agenten stammen diese vom Bereitschaftswert der aktivierten Agenten (zum Beispiel "WhatsApp Web is disconnected" oder "Agent \"Front desk\": Routed on a channel that is not connected"); deaktivierte Agenten werden nie markiert. Bei einem Konto ohne Agenten markieren sie klassische Kampagnen, wie zum Beispiel eine pausierte. Nutzen Sie dies, um ein Dashboard zur Gesundheitsprüfung für den gesamten Kundenstamm zu erstellen, anstatt jeden Kunden einzeln zu öffnen, um zu sehen, welche Agenten deaktiviert sind.

Für zeitreihenbasierte Nachrichten- und Guthabenaktivitäten über alle Kunden hinweg (eine für Diagramme geeignete Reihe statt einer Momentaufnahme zu einem bestimmten Zeitpunkt), siehe GET /analytics/agency-rollup im Analytics-API-Leitfaden.

Ein bereits eingerichtetes Kundenkonto bereitstellen #

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

Ein Snapshot ist eine wiederverwendbare Vorlage: ein oder mehrere KI-Agenten sowie deren Wissensdatenbank, Tools und Medien, die aus Ihrem eigenen Konto erfasst wurden. Zwei Endpunkte integrieren dies in Ihren Bereitstellungsprozess.

Automatisch – jeder neue Kunde erhält es direkt. Markieren Sie einen Snapshot einmalig als Standard, und jedes Konto, das Sie von da an erstellen, wird damit ausgestattet. Dies gilt für Konten, die über POST /v1/subaccounts erstellt wurden, Konten, die Sie im Dashboard erstellen, und Konten, die automatisch erstellt werden, wenn ein Kunde über Ihren Checkout-Link bezahlt.

Suchen Sie zuerst die ID des Snapshots:

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

Legen Sie ihn dann als Standard fest:

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

Das ist die gesamte Integration. Senden Sie {"snapshot_id": null}, um sie wieder zu deaktivieren. Sie können dasselbe über das Dashboard tun, indem Sie auf den Stern auf der Seite Snapshots klicken.

Um auszulesen, was aktuell markiert ist (z. B. bevor ein Bereitstellungsskript entscheidet, ob eines gesetzt werden soll), gibt GET /v1/snapshots/default { "success": true, "data": { "default_snapshot_id": "SNAPSHOT_ID" } } zurück — null, wenn nichts markiert ist. GET /v1/snapshots (wird verwendet, um die oben genannte ID zu finden) gibt dasselbe default_snapshot_id zusammen mit dem vollständigen snapshots-Array zurück, sodass die meisten Integrationen nur diesen einen Aufruf benötigen. Die Felder des vollständigen Snapshot-Objekts finden Sie im Snapshots-Leitfaden.

Auf Abruf – in ein einzelnes Konto installieren. Nützlich für das Onboarding eines bestehenden Kunden oder um einem Kunden später eine zweite Vorlage bereitzustellen.

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

Lassen Sie sub_account_id weg, um es stattdessen in Ihr eigenes Agenturkonto zu installieren. Wie bei den /subaccounts-Endpunkten wird das Zielkonto hier im Pfad oder Body angegeben und nicht über den umgebenden sub_account_id-Parameter.

Wissenswertes, bevor Sie darauf aufbauen:

• Installierte Agenten starten im pausierten Zustand. Verbinden Sie zuerst die Kanäle des Kunden und aktivieren Sie dann den Agenten. Dies gilt sowohl für den automatischen als auch für den On-Demand-Pfad.
• Die Bereitstellung schlägt aufgrund eines Snapshots nie fehl. Wenn die Installation nicht abgeschlossen werden kann, wird das Kundenkonto dennoch erstellt und ist nutzbar – es ist lediglich leer, und Sie können den Snapshot nachträglich anwenden.
• Kanäle, Kalender und OAuth-Verbindungen werden nie kopiert. Jedes Konto verbindet seine eigenen. Tools, die einen einfachen API-Schlüssel verwenden, funktionieren sofort weiter.
• Ein zweimaliges Anwenden erstellt eine zweite Kopie. Es wird nichts überschrieben.

Erstellen Sie die Vorlage selbst über die API #

POST /v1/snapshots · Agenten, benutzerdefinierte Funktionen und Medien über die API

Der obige Abschnitt beschreibt die Verteilung eines Snapshots, der im Dashboard erstellt wurde. Auch der Erstellungsteil ist verfügbar, sodass der gesamte Kreislauf – das Master-Setup einmal zusammenstellen, erfassen und an jeden Kunden weitergeben – vollständig über Code gesteuert werden kann.

Die Komponenten in der Reihenfolge, in der ein Bereitstellungsskript sie verwendet:

1. Erstellen Sie Ihre benutzerdefinierten Funktionen. POST /v1/custom-functions erstellt eine; GET /v1/custom-functions listet Ihre vorhandenen auf, und GET, PUT sowie DELETE unter /v1/custom-functions/{customFunctionId} lesen, aktualisieren und entfernen eine. POST /v1/custom-functions/test führt einen Testlauf einer Definition durch, bevor Sie diese speichern.
2. Erstellen und gestalten Sie den Agenten. POST /v1/agents erstellt ihn, PUT /v1/agents/{agentId} aktualisiert ihn, und PATCH /v1/agents/{agentId}/active mit { "active": false } hält ihn während der Bearbeitung angehalten (der gleiche Aufruf mit true schaltet ihn live). GET /v1/agents listet sie auf.
3. Geben Sie dem Agenten seine Fähigkeiten. POST /v1/agents/{agentId}/custom-functions mit { "custom_function_id": "..." } weist dem Agenten eine Funktion zu; das entsprechende DELETE /v1/agents/{agentId}/custom-functions/{customFunctionId} entfernt sie wieder.
4. Füllen Sie die Medienbibliothek. POST /v1/agents/{agentId}/media-library lädt ein Element hoch (JSON mit base64Data, mimeType, title, description); GET listet die Elemente des Agenten auf, und PATCH/DELETE unter /{itemId} aktualisieren oder entfernen eines.
5. Erfassen Sie es als 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
  }'

Von dort aus geht es weiter wie im vorherigen Abschnitt: Markieren Sie ihn als Standard, damit jeder neue Client damit ausgestattet wird, oder wenden Sie ihn bei Bedarf an. Die Verwaltung erfolgt parallel dazu: PATCH /v1/snapshots/{snapshotId} mit { "name": "..." } benennt einen um, DELETE /v1/snapshots/{snapshotId} löscht einen (und entfernt die Standard-Markierung, falls vorhanden), und GET /v1/snapshots/apply-targets listet jedes Konto auf, in dem Sie eine Installation vornehmen könnten.

Die Endpunkte für Agenten, benutzerdefinierte Funktionen und Medien akzeptieren alle sub_account_id, sodass dieselben Aufrufe auch einen Agenten direkt im Konto eines Clients verwalten können. Snapshot-Aufrufe wirken sich immer auf Ihr Agenturkonto aus – die Vorlage verbleibt bei Ihnen. Vollständige Anforderungs- und Antwortschemas für all diese finden Sie in der API-Referenz.

Verwalten Sie Ihre Preisebenen über die API #

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

Die Pläne, die Sie im SaaS-Modus → Preisebenen verkaufen, können per Code gelesen und geändert werden, sodass Ihr eigenes Admin-Panel oder Bereitstellungsskript einen Plan hinzufügen, einen Preis anpassen oder einen Checkout-Link bereitstellen kann, ohne dass jemand das Dashboard öffnen muss. Authentifizieren Sie sich mit Ihrem Agentur-API-Schlüssel wie bei jedem anderen Aufruf auf dieser Seite; diese Endpunkte sind auf Agenturebene angesiedelt und erfordern daher kein sub_account_id. Jeder Schreibvorgang führt dieselbe Validierung und denselben Stripe-Produkt-und-Preis-Abgleich durch wie das Speichern im Dashboard, sodass ein hier erstellter Plan von einem manuell eingerichteten nicht zu unterscheiden ist.

Listen Sie Ihre Ebenen auf #

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

Antwort

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

Jede Ebene wird mit ihrer tierIndex zurückgegeben — ihrer Position in Ihrer Planliste, über die die anderen drei Aufrufe sie adressieren — und einem sofort einsatzbereiten checkout_url, demselben Link, den Ihnen der Reiter Zahlungen gibt, der bereits auf die White-Label-Domain verweist, auf der dieser Plan verkauft wird.

Fügen Sie eine Ebene hinzu #

Der Body besteht aus einem Ebenen-Objekt; es wird an das Ende Ihrer Liste angehängt.

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

Die Antwort enthält die erstellte Ebene, einschließlich der tierIndex, auf der sie gelandet ist, und ihrer checkout_url.

Bearbeiten Sie eine Ebene #

Senden Sie nur die Felder, die Sie ändern möchten; alles andere am Plan bleibt unverändert.

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

Ein Feld, das die API nicht erkennt, wird abgelehnt, anstatt ignoriert zu werden, und der Fehler benennt es — so kann ein Tippfehler niemals stillschweigend eine Einstellung schreiben, die aktiv aussieht, aber nichts bewirkt. Das Ändern des Preises, der Credits, der Währung oder des Abrechnungszyklus erstellt einen neuen Preis in Ihrem Stripe; Kunden, die bereits abonniert haben, behalten das, wofür sie sich angemeldet haben.

Löschen Sie eine Ebene #

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

Dieselbe Regel wie im Dashboard: Ein Plan, der noch aktive Abonnenten hat, kann nicht gelöscht werden. Die Anfrage wird abgelehnt und teilt Ihnen mit, wie viele Abonnenten sich darauf befinden — kündigen oder migrieren Sie diese zuerst. Ein erfolgreiches Löschen antwortet mit Ihren verbleibenden Ebenen, die bereits neu nummeriert sind.

Die Felder einer Ebene #

Die Testphasen-Felder sind nur für Pläne mit einer Testphase relevant: Wenn Sie einen Tarif mit trial_days: 0 speichern, werden sie verworfen. Die Stripe-Produkt- und Preis-IDs des Plans werden für Sie verwaltet und können nicht manuell festgelegt werden.

Drei Dinge, die Sie beachten sollten:

• Tarif-Indizes sind Positionen, keine permanenten IDs. Das Löschen eines Tarifs verschiebt alle nachfolgenden Tarife um eine Position nach oben. Rufen Sie die Liste daher nach jeder Änderung erneut ab – und kopieren Sie die Checkout-Links, die Sie veröffentlicht haben, neu, genau wie Sie es nach dem Löschen eines Tarifs im Dashboard tun würden.
• Der SaaS-Modus muss zuerst eingerichtet werden. Diese Endpunkte erfordern ein Agenturkonto mit White-Labeling und einem bereits gespeicherten Stripe-Schlüssel; ohne diesen gibt es kein Stripe-Konto, auf dem das Produkt und der Preis des Tarifs hinterlegt werden können.
• Zwanzig Tarife sind das Limit, genau wie im Dashboard. Das Feld max_tiers in der Listenantwort zeigt Ihnen das aktuelle Limit an.

Vollständige Anforderungs- und Antwort-Schemas finden Sie in der API-Referenz unter Agency.

Legen Sie Ihren Preis pro Credit über die API fest #

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

Der Preis, den Kunden für Ad-hoc-Aufladungen zahlen (SaaS-Modus → Preis pro Credit), kann auch per Code ausgelesen und geändert werden. Dies ist für Fälle gedacht, in denen sich der Preis automatisch anpassen muss: Eine Agentur, die Credits in einer Währung verkauft, aber in einer anderen abrechnet, kann den Preis durch einen geplanten Job bei Wechselkursänderungen anpassen lassen, anstatt dass jemand dies jede Woche manuell erledigen muss.

Aktuellen Preis abrufen #

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

Antwort

{
  "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 ist der niedrigste Preis, den die Plattform in dieser Währung zulässt, sodass ein Job einen neuen Preis prüfen kann, bevor er ihn übermittelt. Alle drei Werte sind null, bis ein Preis festgelegt wurde.

Preis ändern #

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

Senden Sie nur das, was Sie ändern möchten. price_per_credit_cents ist der Preis in der kleinsten Währungseinheit (130 = R$1,30); currency ist ein ISO-Code in Kleinbuchstaben; note ist eine optionale Zeile mit bis zu 200 Zeichen, die Kunden direkt unter dem Preis pro Credit auf ihrer Abrechnungsseite angezeigt wird – nützlich für einen Referenzpreis in einer anderen Währung, wie z. B. “USD 0,25 pro Credit zu unserem Referenzkurs”. Senden Sie "note": "", um sie zu entfernen. Die Antwort hat das gleiche Format wie beim Abruf oben, sodass ein Job vergleichen und den Schreibvorgang überspringen kann, wenn sich nichts geändert hat.

Es gelten dieselben Regeln wie im Dashboard: Der Preis darf das Plattform-Minimum für diese Währung nicht unterschreiten und das Konto benötigt White Labeling. Im Gegensatz zu den Endpunkten für Preisstufen ist kein Stripe-Schlüssel erforderlich, um diesen Wert zu lesen oder zu ändern.

Geben Sie einem Job einen Schlüssel mit eingeschränkten Rechten #

Die Eingabe Ihres vollständigen Agenturschlüssels in einen Scheduler gewährt mehr Zugriff, als für eine Preisaktualisierung erforderlich ist. Erstellen Sie stattdessen einen bereichsbeschränkten Schlüssel (scoped key), der auf den Bereich Agentur-Guthabenpreis begrenzt ist: Dieser Schlüssel kann nur den Preis pro Guthaben lesen und ändern – er hat keinen Zugriff auf Unterkonten, Pläne, Guthaben oder Ihre Stripe-Verbindung.

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

Die Antwort enthält den neuen Schlüssel api_key einmalig – er wird danach nie wieder angezeigt, speichern Sie ihn also sofort. Setzen Sie "read_only": true für einen Schlüssel, der den Preis nur lesen muss, und fügen Sie "expires_at" (ein ISO-Datum) hinzu, wenn er automatisch ablaufen soll. Nur der Schlüssel des Kontoinhabers kann bereichsbeschränkte Schlüssel erstellen; listen oder widerrufen Sie diese mit GET /v1/api-keys und DELETE /v1/api-keys/{id}.

Ein Unterkonto Ihre Preisgestaltung lesen lassen #

GET /v1/subaccounts/agency-pricing

Jeder andere Endpunkt auf dieser Seite wird mit Ihrem Agenturschlüssel aufgerufen, wobei optional ein Kunde über sub_account_id adressiert wird. Dieser hier ist das Gegenteil: Er wird mit dem eigenen API-Schlüssel des Unterkontos aufgerufen, ohne sub_account_id, sodass die eigene Aufladeseite eines Kunden (oder eine Integration, die Sie für ihn erstellen) anzeigen kann, was Sie ihm berechnen, ohne jemals Ihr Agenturkonto zu sehen.

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

Antwort

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

Dies spiegelt genau das wider, was GET /v1/agency/pricing-tiers und GET /v1/agency/credit-price für Sie als Agentur zurückgeben, abzüglich dessen, was der Kunde nicht sehen muss (Stripe-IDs, max_tiers usw.). Es funktioniert nur für ein Konto, das tatsächlich ein Unterkonto mit einer verknüpften Agentur ist — ein Aufruf von Ihrem eigenen Agenturkonto aus führt zu einem Berechtigungsfehler.

Wichtige Hinweise #

• Verwenden Sie Ihren Agenturschlüssel. Authentifizieren Sie jeden Aufruf mit dem API-Schlüssel Ihres Agenturkontos – nicht mit dem des Unterkontos. Der Parameter sub_account_id leitet die Aktion weiter.
• Guthaben wird vom Unterkonto abgebucht. Käufe und wiederkehrende Gebühren belasten das Guthaben des jeweiligen Unterkontos, nicht Ihres.
• Ein 404 bedeutet „nicht Ihr Unterkonto“. Überprüfen Sie die ID und stellen Sie sicher, dass es sich um ein Konto handelt, das Sie verwalten.
• Der Parameter ist überall dort optional, wo er akzeptiert wird. Wenn Sie ihn weglassen, wirkt der Endpunkt auf Ihr Agenturkonto, sodass Sie eine Integration für beides verwenden können.

Verwandte Themen #

• API-Zugriff – Authentifizierung, Basis-URL, Fehler, Ratenbegrenzungen.
• Unterkonten – Auflisten und Verwalten der Konten, auf die Sie zugreifen können.
• Automatische Aufladung von Unterkonten – Guthaben für ein Unterkonto per Webhook + API gewähren.
• KI-Agenten-API: KI-Agenten erstellen und konfigurieren.
• Kampagnen-API: die veraltete klassische Kampagnenressource, einschließlich der vollständigen Feldreferenz.
• Kanalverbindungs-API – Kanäle eines Kunden verbinden.
• Einstiegspunkte-API: entscheiden, welcher Agent ein neues Gespräch übernimmt.
• Analytics-API-Handbuch (im API-Bereich) – das Rollup für Agentur-Unterkonten und jeder andere Reporting-Endpunkt.
• Snapshots – was ein Snapshot erfasst und wie man einen im Dashboard erstellt.