Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

API für Dispositionscodes

Mit der Disposition Codes API können Sie in Ihrer Integration folgende Aktionen ausführen:

Listen mit Dispositionscodes für eine Instanz, eine Warteschlange oder eine Sitzung abrufen
Dispositionscodes oder Notizen (oder beides) für einen zuvor abgeschlossenen Anruf oder eine zuvor abgeschlossene Chatsitzung aktualisieren

Authentifizierung und Basis-URL

Für alle Endpunkte in diesem Dokument wird die Standardauthentifizierung mit API-Tokens verwendet, wobei ein API-Nutzertoken (Bearertoken) zum Einsatz kommt.

Basis-URL: https://SUBDOMAIN.REGION_CODE.ccaiplatform.com

Liste mit Dispositionscodes abrufen

Rufen Sie die verfügbaren Dispositionscodes ab. Sie können Abfragen auf Instanz-, Warteschlangen- und Sitzungsebene ausführen.

Nach Instanz

Gibt die vollständige Dispositionscode-Struktur für die Instanz zurück, einschließlich aller mehrstufigen Dispositionscodes.

Beispielanfrage

Mit der folgenden Anfrage wird die vollständige Liste der Dispositionscodes abgerufen:

GET /api/v1/disposition_codes
Authorization: Bearer {token}
Content-Type: application/json

Beispielantwort

Die folgende Beispielantwort zeigt die vollständige Liste der Dispositionscodes:

{
  "disposition_codes": [
    {
      "id": 1,
      "name": "Issue Resolved",
      "full_path": "/Support/Issue Resolved",
      "children": []
    },
    {
      "id": 2,
      "name": "Escalated",
      "full_path": "/Support/Escalated",
      "children": [
        {
          "id": 3,
          "name": "Tier 2",
          "full_path": "/Support/Escalated/Tier 2",
          "children": []
        }
      ]
    }
  ]
}

Nach Warteschlange

Gibt die Dispositionscodes zurück, die einer Warteschlange zugewiesen sind. Wenn keine warteschlangenspezifische Liste konfiguriert ist, wird die globale Liste (auf Instanzebene) zurückgegeben.

Beispielanfrage

Mit der folgenden Anfrage werden Dispositionscodes für eine Warteschlange abgerufen:

GET /api/v1/disposition_codes?queue_id=QUEUE_ID
Authorization: Bearer TOKEN
Content-Type: application/json

Suchparameter

Parameter	Typ	Erforderlich	Beschreibung
`queue_id`	Integer	Ja	Die ID der Warteschlange, für die Dispositionscodes abgerufen werden sollen.

Nach Sitzung

Gibt die Dispositionscodes zurück, die für eine bestimmte Sitzungs-ID verfügbar sind, basierend auf der letzten Warteschlange, durch die die Sitzung weitergeleitet wurde.

Beispielanfrage

Mit der folgenden Anfrage werden Dispositionscodes für eine Sitzung abgerufen:

GET /api/v1/disposition_codes?session_id=SESSION_ID
Authorization: Bearer TOKEN
Content-Type: application/json

Suchparameter

Parameter	Typ	Erforderlich	Beschreibung
`session_id`	Integer	Ja	Die Sitzungs-ID.

Dispositionscode und Notizen aktualisieren

Senden Sie einen aktualisierten Dispositionscode oder aktualisierte Notizen (oder beides) für einen zuvor abgeschlossenen Anruf oder eine zuvor abgeschlossene Chatsitzung. Dadurch wird ein neuer Dispositionsdatensatz und eine neue CRM-Notiz erstellt. Der ursprüngliche CRM-Datensatz wird nicht bearbeitet.

Beispielanfrage

Mit der folgenden Anfrage werden der Dispositionscode oder die Notizen für eine Sitzung aktualisiert:

POST /api/v1/sessions/SESSION_ID/disposition
Authorization: Bearer TOKEN
Content-Type: application/json

Pfadparameter

Parameter	Typ	Erforderlich	Beschreibung
`session_id`	Integer	Ja	Die Sitzungs-ID des Anrufs oder Chats, der aktualisiert werden soll.

Beispiel für einen Anfragetext

Das folgende Beispiel zeigt einen Anfragetext:

{
  "disposition_code": {
    "id": 5,
    "full_path": "/Support/Verification/Pending Documents"
  },
  "notes": "Customer must upload documents via portal."
}

Parameter für den Anfragetext

Parameter	Typ	Erforderlich	Beschreibung
`disposition_code`	Objekt	Bedingt	Der aktualisierte Dispositionscode. Mindestens einer der Parameter `disposition_code` oder `notes` muss vorhanden sein.
`disposition_code.id`	Integer	Ja (wenn `disposition_code` angegeben)	Die ID des Dispositionscodes.
`disposition_code.full_path`	String	Ja (wenn `disposition_code` angegeben)	Der vollständige hierarchische Pfad des Dispositionscodes, z. B. `/Support/Verification/Pending Documents`. Wird zur Validierung anhand der Dispositionsstruktur der Sitzung verwendet.
`notes`	String	Nein	Die aktualisierten Notizen des Agenten. Weitere Informationen finden Sie in der Tabelle Verhalten von Notizen.

Verhalten von Notizen

Wert	Verhalten
Vorhanden mit Text, z. B. `"notes": "Updated notes"`	Ersetzt die vorhandene Notiz durch den neuen Text.
Vorhanden als leerer String ("notes": "")	Löscht die vorhandene Notiz explizit. Die Sitzungsmetadatendatei enthält die Notiz nicht mehr. Im CRM-Verlauf bleiben vorherige Datensätze erhalten.
Ausgelassen (Feld nicht in der Anfrage vorhanden)	Die vorhandene Notiz bleibt unverändert.

Disposition „Nicht anrufen“

Wenn Sie eine Disposition „Nicht anrufen“ senden möchten, verwenden Sie disposition_code.id: -1. Dies wird nur akzeptiert, wenn die Funktion „Nicht anrufen“ für die Instanz aktiviert ist und eine Disposition „Nicht anrufen“ konfiguriert ist. Andernfalls gibt die API 422 Unprocessable Entity mit der Meldung „Do Not Call disposition is not enabled for this tenant“ (Die Disposition „Nicht anrufen“ ist für diesen Mandanten nicht aktiviert) zurück.

Agentenzuweisung

Die API enthält keine Agentenidentität. Das System weist die Disposition in der folgenden Reihenfolge zu:

Der Agent, der die Disposition ursprünglich für diese Sitzung gesendet hat.
Wenn keine ursprüngliche Disposition vorhanden ist, der letzte Agent, der am Anruf oder Chat teilgenommen hat.

Wenn keines von beiden vorhanden ist, gibt die API 422 Unprocessable Entity zurück.

Validierung

In der folgenden Liste werden die Validierungsregeln beschrieben:

Der Anruf oder Chat der Sitzung muss beendet sein. Wenn Sie versuchen, die Disposition für eine aktive Sitzung zu aktualisieren, wird 422 Unprocessable Entity zurückgegeben.
Die Parameter disposition_code.id und disposition_code.full_path werden anhand der Dispositionsstruktur der Sitzung validiert (basierend auf der Warteschlange, durch die die Sitzung zuletzt weitergeleitet wurde).
Die Administratoreinstellung allow_disposition_edit ist nur eine UI-Steuerung. Mit der öffentlichen API können Dispositionsdaten unabhängig von dieser Einstellung immer aktualisiert werden.

Beispielantwort

Das folgende Beispiel zeigt eine Antwort auf eine erfolgreiche Anfrage:

{
  "session_id": 12345,
  "disposition": {
    "id": 5,
    "name": "Verification Pending",
    "full_path": "/Support/Verification/Pending Documents",
    "notes": "Customer must upload documents via portal.",
    "submitted_at": "2026-03-13T10:15:01Z"
  }
}

Hinweis: Das Feld name wird vom Server anhand der angegebenen Werte für id und full_path aus der Dispositionsstruktur aufgelöst. Es wird zur Vereinfachung in der Antwort zurückgegeben.

Sitzungsmetadaten

Wenn eine Disposition mit dieser API aktualisiert wird, geschieht Folgendes:

Externer Speicher: Die Sitzungsmetadatendatei wird neu generiert und überschreibt die vorhandene Metadatendatei.
CRM: Es wird eine neue Notiz erstellt, wobei der Audit-Trail beibehalten wird.

Fehlerbehandlung

In diesem Abschnitt wird die Fehlerbehandlung beschrieben.

Häufige Statuscodes

Status	Bedingung	Beispielmeldung
`400 Bad Request`	Erforderliche Felder fehlen (`disposition_code` und `notes` sind beide nicht vorhanden) oder ungültiges Format.	"At least one of disposition_code or notes must be present."
`401 Unauthorized`	Ungültiges oder fehlendes API-Token.	"Unauthorized"
`403 Forbidden`	Der API-Nutzer hat keinen Zugriff auf die angegebene Sitzung oder den angegebenen Mandanten.	"Forbidden"
`404 Not Found`	Sitzung nicht gefunden oder nicht vorhanden.	"Session not found."
`422 Unprocessable Entity`	Verschiedene Validierungsfehler. Weitere Informationen finden Sie in der Tabelle Szenarien für „422 Unprocessable Entity“.	Weitere Informationen finden Sie in der Tabelle Szenarien für „422 Unprocessable Entity“.

Szenarien für „422 Unprocessable Entity“

Szenario	Fehlermeldung
Anruf- oder Chatsitzung ist noch aktiv	"Session has not ended. Disposition can only be updated for completed sessions."
Dispositionscode-ID nicht in der Struktur der Sitzung gefunden	"Disposition code is invalid for this session's queue."
Disposition „Nicht anrufen“ gesendet, Funktion aber nicht aktiviert	"Do Not Call disposition is not enabled for this tenant."
Kein Agententeilnehmer für die Zuweisung auflösbar	"Unable to determine agent for disposition attribution."

Beispielantwort

Das folgende Beispiel zeigt eine Fehlerantwort:

{
  "error": {
    "code": "session_not_ended",
    "message": "Session has not ended. Disposition can only be updated for completed sessions.",
    "details": {
      "session_id": 12345
    }
  }
}

Typischer Integrationsablauf

Hier sehen Sie einen typischen Integrationsablauf:

Dispositionscodes für die entsprechende Warteschlange oder Sitzung abrufen:
- GET /api/v1/disposition_codes?session_id=SESSION_ID
Die Dispositionsstruktur dem Nutzer oder automatisierten System zur Auswahl präsentieren.
Die aktualisierte Disposition senden:
- POST /api/v1/sessions/SESSION_ID/disposition
- Fügen Sie den ausgewählten `disposition_code` mit id und full_path sowie alle Notizen ein.
Antwort verarbeiten:
- Bei „200 OK“: Die Disposition wurde aktualisiert. CRM-Datensätze werden automatisch aktualisiert.
- Bei einem Fehler: Fehlermeldung anzeigen und gegebenenfalls noch einmal versuchen oder eskalieren.

CRM-Verhalten

Wenn eine Disposition mit dieser API gesendet wird, geschieht Folgendes:

Im verbundenen CRM, z. B. Salesforce, ServiceNow, Zendesk, Dynamics oder HubSpot, wird eine neue CRM-Notiz erstellt. Die ursprüngliche Notiz wird nicht geändert.
Bei externem Speicher wird die Sitzungsmetadatendatei mit den aktualisierten Dispositionsdaten überschrieben.

Beschränkung

HubSpot-Anrufaktivitäten enthalten die skalare Property hs_call_disposition, die bei jeder Aktualisierung der Disposition überschrieben (nicht angehängt) wird. Der vollständige Verlauf wird zwar in HubSpot-Notizen beibehalten, die Aktivitätseigenschaft spiegelt jedoch nur den letzten Dispositionscode wider.

API für Dispositionscodes Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

Authentifizierung und Basis-URL

Liste mit Dispositionscodes abrufen

Nach Instanz

Nach Warteschlange

Nach Sitzung

Dispositionscode und Notizen aktualisieren

Verhalten von Notizen

Disposition „Nicht anrufen“

Agentenzuweisung

Validierung

Sitzungsmetadaten

Fehlerbehandlung

Häufige Statuscodes

Szenarien für „422 Unprocessable Entity“

Typischer Integrationsablauf

CRM-Verhalten

Beschränkung

API für Dispositionscodes