Fehlerbehandlung, Wiederholungsversuche und Aufrufreihenfolge in benutzerdefiniertem CRM (generische API)

In diesem Dokument wird das Verhalten der Funktion „Benutzerdefiniertes CRM (generische API)“ der CCAI Platform beschrieben, wenn Ihre CRM-Endpunkte andere Antworten als HTTP 200 "Success." zurückgeben. Es dient als Verhaltensreferenz für Integratoren, die API-Konto- und API-Eintragsendpunkte konfigurieren.

Allgemeine Ausführungsreihenfolge und Beziehungen

Wenn eine Interaktion eine benutzerdefinierte CRM-Integration auslöst, ruft die Plattform Ihre Endpunkte in dieser Reihenfolge auf:

  1. Vorgänge auf Kontoebene (API-Konto) – Kontakt

    Beispiele:

    • Kontakt finden

    • Kontakt erstellen

    • Kontakt aktualisieren

  2. Vorgänge auf Datensatzebene (API-Datensatz) – Ticket oder Fall

    Beispiele:

    • Suchen Sie nach einem Ticket.

    • Erstellen Sie ein Ticket.

    • Ticket aktualisieren

  3. Aktionen nach der Sitzung (falls konfiguriert)

    Beispiele:

    • Fügen Sie einen Kommentar oder eine Notiz hinzu.

    • Laden Sie einen Anhang oder ein Transkript hoch.

    • Aktualisierungen der Nachbereitung anwenden.

In früheren Schritten werden in der Regel IDs erstellt, die in späteren Schritten verwendet werden können. Beispielsweise kann eine contact_id an die Ticketerstellung übergeben werden, wenn sie in der Nutzlastvorlage Ihres Endpunkts enthalten ist. Eine ticket_id ist für Aktionen nach der Sitzung in typischen generischen API-Konfigurationen erforderlich. Beachten Sie, dass nicht jeder Endpunkt so konfiguriert ist, dass eine ID extrahiert wird. Weitere Informationen finden Sie unter Wichtige Nuance: 2xx + fehlende ID bei Endpunkten, die IDs extrahieren.

Wichtige Nuance: 2xx + fehlende ID bei Endpunkten, die IDs extrahieren

Nicht jeder benutzerdefinierte CRM-Endpunkt extrahiert eine ID aus der empfangenen Antwort. Dieses Verhalten gilt nur für Endpunkte, die mit einem response_data_location und (für Erstellungsendpunkte) einem custom_id_location konfiguriert sind – in der Regel Such-Endpunkte (Extrahieren der ID eines vorhandenen Datensatzes) und Erstellungsendpunkte (Extrahieren der ID eines neu erstellten Datensatzes). Endpunkte wie Kommentare, Anhänge und Updates extrahieren keine IDs aus ihren Antworten.

Auswirkungen einer fehlenden ID auf ID-extrahierende Endpunkte

  • Für Such-Endpunkte: Eine 200 OK-Antwort ohne übereinstimmenden Eintrag (und daher ohne extrahierbare ID) ist ein normales „Nicht gefunden“-Verhalten. Wenn für Ihre Instanz skip_account_creation oder skip_record_creation aktiviert ist, wird die Plattform absichtlich mit einem Nullwert für contact_id oder ticket_id fortfahren, anstatt zu versuchen, die Ressource zu erstellen. Das ist ein erwartetes Verhalten bei diesen Konfigurationen und keine Fehlkonfiguration.

  • Für Erstellungsendpunkte: Eine 200 OK-Antwort, die die neu erstellte ID nicht am konfigurierten Speicherort enthält, ist ein Konfigurations- oder Antwortvertragsproblem. Die HTTP-Anfrage war erfolgreich, sodass keine Wiederholungen ausgelöst werden. Nachfolgende Schritte können jedoch mit fehlenden Daten fortgesetzt werden.

  • In beiden Fällen wird der Fehler (sofern es sich um einen Fehler handelt) als fehlende Daten und nicht als Endpunktfehler angezeigt, was beim Debugging verwirrend sein kann.

Anleitung für Integratoren

  • Bei Erstellungsvorgängen sollte die Rückgabe der erwarteten ID am konfigurierten Speicherort Teil Ihres Erfolgsvertrags sein, nicht nur die Rückgabe von 2xx. Behandeln Sie eine fehlende ID als Konfigurations- oder Antwortvertragsproblem, das untersucht werden sollte.

  • Bei Suchvorgängen ist es akzeptabel, 200 OK ohne Übereinstimmung zurückzugeben. Wenn Ihre Instanz absichtlich auf „Lookup ohne Erstellung“-Mustern basiert (z. B. skip_account_creation = true), dokumentieren Sie diese Entscheidung, damit nachgelagerte Endpunkte wissen, wie sie mit fehlenden IDs umgehen sollen.

  • Prüfen Sie beim Testen Folgendes:

    • Bei Erstellungsendpunkten ist die ID zuverlässig in der Antwort und an der genauen Stelle vorhanden, die im benutzerdefinierten CRM konfiguriert ist.

    • Bei Such-Endpunkten entspricht das Downstream-Verhalten der Plattform der Skip-Flag-Konfiguration Ihrer Instanz.

Fehlerbehandlung: Übersicht

Wenn ein Endpunkt eine nicht erfolgreiche Antwort (nicht 2xx) zurückgibt oder nicht antwortet:

  • Die Plattform kann die Anfrage wiederholen:

    • Einmal sofort für einige Status.

    • Über einen längeren Zeitraum für Fehler, die wiederholt werden können.

  • Nachgelagerte Schritte können sich verzögern, während die Plattform einen vorgelagerten Schritt wiederholt.

  • Einige Fehler werden als nicht wiederholbar behandelt (z. B. Konfigurations- oder Validierungsfehler).

Die detaillierten Wiederholungsregeln werden unter Wiederholungs- und Backoff-Verhalten beschrieben. Die Beziehung zwischen Fehlern und nachgelagerten Aufrufen wird unter Verkettungs- und Abhängigkeitsregeln beschrieben.

Verkettungs- und Abhängigkeitsregeln

Das benutzerdefinierte CRM-Verhalten unterliegt der CRM-Konfiguration Ihrer Instanz, insbesondere den Einstellungen, die unter Erstellung von CRM-Konto und ‑Datensatz überspringen dokumentiert sind. In diesem Dokument werden diese Einstellungen mit ihren Backend-Konfigurationsnamen (skip_account_creation, skip_account_lookup, skip_record_creation) bezeichnet, da sie in den folgenden JSON-Konfigurationsbeispielen so angezeigt werden.

In diesen Einstellungen ist die Plattform darauf ausgerichtet, die Kette nach Möglichkeit fortzusetzen, z. B. durch Erstellen eines anonymen Kontakts, wenn die Suche fehlschlägt und die Kontoerstellung aktiviert ist, anstatt immer einen „harten Stopp“ zu erzwingen.

Auswirkungen von Kontofehlern auf Datensatzvorgänge

Der Schritt „Datensatz“ (Ticket/Fall) kann auch dann ausgeführt werden, wenn der Schritt „Konto“ keinen Kontakt erzeugt. Das genaue Verhalten hängt jedoch von der Konfiguration der Instanz ab.

Je nach Konfiguration kann die Plattform Folgendes tun:

  • Erstellen Sie einen anonymen Kontakt als Fallback und fahren Sie mit der Ticketerstellung fort.

  • Fahre mit der Aufzeichnung der Schritte ohne contact_id fort, wenn die Kontosuche oder die Kontoerstellung übersprungen werden soll.

Was bedeutet das für Ihre Endpunkte?

  • Wenn beim Erstellen eines Tickets die contact_id fehlt, deutet das in der Regel auf eine Instanzkonfiguration hin, bei der die Kontosuche oder die Kontoerstellung deaktiviert ist.

  • Wenn für Ihre Instanz Konten erforderlich sind, sollten Sie ein fehlendes contact_id als Signal betrachten, das untersucht werden sollte, anstatt Tickets ohne Kontakt einzufügen.

  • Wenn Ihre Konfiguration die Ticketerstellung ohne Kontakt zulässt, achten Sie darauf, dass Ihr Ticketendpunkt diesen Fall explizit und vorhersehbar verarbeitet.

Auswirkungen von Aufzeichnungsfehlern auf Aktionen nach der Sitzung

Bei generischen API-Konfigurationen, bei denen die Ticket-Suche konfiguriert ist, sendet die Plattform keine Aufrufe nach der Sitzung, z. B. call_finished, chat_finished, email_finished, save_call_recording, save_chat_history, update_ticket und done_ticket, bis ein ticket_id vorhanden ist.

Wenn ein Endpunkt nach der Sitzung ohne ticket_id aufgerufen wird, deutet das in der Regel auf eine der folgenden Bedingungen hin:

  • Die Ticket-Suche ist für die Instanzkonfiguration deaktiviert, was für eine typische generische API-Einrichtung ungewöhnlich ist.

  • In der Nutzlastvorlage wurde die Variable ticket_id weggelassen. Dies ist ein Konfigurationsproblem, das untersucht werden sollte.

Was bedeutet das für Ihre Endpunkte?

  • Wenn ticket_id bei Aufrufen nach der Sitzung fehlt, sollten Sie dies als Konfigurationssignal betrachten, das untersucht werden muss, und nicht als erwartetes Verhalten, das stillschweigend hingenommen werden kann.

  • Wenn für Ihre Konfiguration absichtlich keine Ticketabfrage erforderlich ist, konfigurieren Sie Ihre Endpunkte nach der Sitzung so, dass ein fehlendes ticket_id ordnungsgemäß verarbeitet wird. Protokollieren Sie beispielsweise das Problem und führen Sie keine Aktion aus oder geben Sie eine klare, gut strukturierte Fehlermeldung zurück, anstatt abzustürzen.

Wiederholungs- und Backoff-Verhalten

Wiederholungsversuche erfolgen auf drei Ebenen:

  1. Sofortige Wiederholung auf HTTP-Ebene (ein schneller zweiter Versuch).

  2. Wiederholungsversuch auf Adapterebene (schnelle Wiederherstellung bei Netzwerkfehlern und bestimmten vorübergehenden Antworten).

  3. Wiederholungsversuche auf Befehlsebene (Longtail-Wiederholungsversuche über Tage hinweg).

Sofortige Wiederholung auf HTTP-Ebene (schnelle Wiederholung)

Bei bestimmten vorübergehenden Status unternimmt die Plattform insgesamt bis zu zwei Versuche (ein erster Versuch und ein sofortiger Wiederholungsversuch). Dies gilt in der Regel für die folgenden Fehlerstatus:

  • 408, 413, 429, 500, 502, 503, 504, 521, 522 und 524.

Wiederholungsversuch auf Adapterebene (schnelle Netzwerkwiederherstellung)

Zwischen dem HTTP-Aufruf und dem Zeitplan auf Befehlsebene verarbeitet eine Zwischenebene für Wiederholungsversuche im CRM-Adapter (command_runner.js) Fehler, die überhaupt keine HTTP-Antwort erzeugen oder mit bestimmten vorübergehenden Nachrichten übereinstimmen:

  • Sofortiges erneutes Einreihen in die Warteschlange: Wird durch Fehler auf TCP-/Socket-Ebene ausgelöst – ECONNRESET, ENOTFOUND, ESOCKETTIMEDOUT, ETIMEDOUT, ECONNREFUSED, EHOSTUNREACH, EPIPE, EAI_AGAIN. Dies sind Netzwerkfehler, die auftreten, bevor eine HTTP-Antwort empfangen wird.

  • Wiederholung mit 30 Sekunden Verzögerung: Wird ausgelöst, wenn die Fehlermeldung "Too Early" (HTTP 425), "Service Unavailable" oder "Unordered Collection" lautet.

  • Nicht wiederholbar auf dieser Ebene: Alles andere fällt auf den Wiederholungszeitplan auf Befehlsebene (Ebene 3) zurück.

Warum das für Integratoren wichtig ist

Diese Fehler treten auf, wenn die Plattform keine TCP-Verbindung zu Ihrem Endpunkt herstellen oder aufrechterhalten kann. Das bedeutet, dass sie häufig auf ein Problem auf Ihrem Server hinweisen (Server ausgefallen, Verbindungen werden abgelehnt oder die Verbindung wird während der Anfrage unterbrochen) und nicht nur auf die interne Infrastruktur. In der Praxis führt dies dazu, dass einige Netzwerkfehler viel schneller behoben werden als im 7-tägigen Zeitplan auf Befehlsebene – oft innerhalb von Sekunden.

Wiederholungsversuche auf Befehlsebene (~7 Tage, 14 Versuche)

Wenn ein Vorgang fehlschlägt und wiederholt werden kann, kann die Plattform ihn bis zu 14-mal über einen Zeitraum von etwa 7 Tagen nach folgendem Zeitplan wiederholen:

  10s → 1m → 5m → 30m → 1h → 6h → 6h → 12h → 1d → 1d → 1d → 1d → 1d → 1d

Dieses Longtail-Wiederholungsverhalten kann für Folgendes gelten:

  • Kontovorgänge.

  • Vorgänge aufzeichnen.

  • Vorgänge nach der Sitzung.

Nicht wiederholbare Fehler

Einige Fehler werden als nicht wiederholbar behandelt, z. B.:

  • Konfigurations- oder Validierungsfehler (z. B. erforderliche Endpunkte sind nicht oder falsch konfiguriert).

  • Bestimmte interne Fehlerkategorien, die von der Plattform erkannt werden.

Wenn du sicherstellen möchtest, dass ein Fehler als dauerhaft behandelt wird (keine Wiederholungsversuche), wende dich an den Support oder dein Implementierungsteam, um zu erfahren, wie du in deiner spezifischen Konfiguration einen nicht wiederholbaren Fehler angeben kannst.

Zeitüberschreitungen und Netzwerkfehler

Die Plattform verarbeitet zwei unterschiedliche Pfade:

  1. Zeitüberschreitungen auf Anwendungsebene: Wenn die konfigurierte HTTP-Zeitüberschreitung überschritten wird (die Anfrage wurde gesendet, aber es wurde keine Antwort empfangen), löst die Plattform einen internen Fehler aus, der auf Befehlsebene (Ebene 3) wiederholt werden kann. Das bedeutet, dass die Anfrage dem standardmäßigen Backoff-Zeitplan folgt (bis zu 14 Wiederholungsversuche über ca. 7 Tage).

  2. Fehler auf TCP-/Socket-Ebene: Wenn die Verbindung auf Netzwerkebene fehlschlägt, bevor eine HTTP-Antwort empfangen wird (z. B. ETIMEDOUT, ESOCKETTIMEDOUT und ECONNREFUSED), werden diese von der Adapterschicht (Schicht 2) abgefangen und der Befehl wird sofort wieder in die Warteschlange gestellt. Die Wiederherstellung nach solchen Fehlern erfolgt in der Regel viel schneller – oft innerhalb von Sekunden und nicht nach dem 7-tägigen Zeitplan.

Warum die Unterscheidung wichtig ist

  • Bei einem Anwendungs-Timeout (Ihr Server hat die Verbindung akzeptiert, aber nicht rechtzeitig geantwortet) wird die Wiederholung langsamer ausgeführt.

  • Bei einem Fehler auf Netzwerkebene (Ihr Server konnte überhaupt nicht erreicht werden) wird der Versuch viel schneller wiederholt.

  • In beiden Fällen wurde die Anfrage möglicherweise teilweise verarbeitet. Endpunkte sollten daher idempotent sein. Weitere Informationen finden Sie unter Ausfallsichere Endpunkte erstellen (Idempotenz und Designtipps).

Matrix für Statuscode und Zeitüberschreitungsverhalten (mit Beispielen)

In den folgenden Tabellen und Beispielen wird beschrieben, wie die CCAI-Plattform mit verschiedenen HTTP-Statuscodes, Zeitüberschreitungen und Netzwerkfehlern umgeht.

Tabelle mit Zusammenfassung der Ergebnisse

Die ID-bezogenen Zeilen in der folgenden Tabelle gelten nur für Endpunkte, die so konfiguriert sind, dass sie eine ID aus der Antwort extrahieren, z. B. Such- oder Erstellungsendpunkte. Die meisten anderen Endpunkte führen keine Extraktion der Antwort-ID durch.

Ergebnis Beispiele Sofortige HTTP-Wiederholung? Longtail-Wiederholungsversuche (~7 Tage)? Nachgelagerte Auswirkungen
Erfolgreiche Antwort für einen Endpunkt, der IDs extrahiert 2xx + erwartete ID am konfigurierten Antwortspeicherort vorhanden. Nein Nein Downstream wird mit der extrahierten ID fortgesetzt.
Suche ohne Übereinstimmung 2xx, aber am konfigurierten Speicherort wurde kein Eintrag gefunden. Nein Nein Normales „Nicht gefunden“-Verhalten. Wenn skip_account_creation oder skip_record_creation aktiviert ist, werden nachgelagerte Vorgänge absichtlich mit Null-IDs fortgesetzt.
Wiederkehrende 2xx ohne ID erstellen 2xx von einem Erstellungsendpunkt, aber die ID des neuen Datensatzes fehlt am konfigurierten Speicherort. Nein Nein Downstream kann mit fehlenden Daten fortfahren. Behandeln Sie das Problem als Konfigurations- oder Antwortvertragsproblem.
Erfolgreiche Antwort von einem Endpunkt, der keine ID extrahiert 2xx von Endpunkten wie Notiz-, Aktualisierungs- oder Anhangsaktionen, die keine IDs extrahieren. Nein Nein Die nachgelagerte Verarbeitung erfolgt gemäß der Befehlskette und der Instanzkonfiguration.
Vorübergehender Fehler 408, 413, 429, 500, 502, 503, 504, 521, 522 und 524. Ja (insgesamt zwei Versuche) Oft ja Nachgelagerte Schritte können sich während der Wiederholungsversuche verzögern.
Andere Fehler 400, 401, 403, 404 und andere 4xx/5xx. Nein Oft ja Nachgelagerte Schritte können sich während der Wiederholungsversuche verzögern.
Konfigurations-/Validierungsfehler Fehlkonfiguration, fehlende Endpunkte. – Nein Die Kette kann je nach Konfiguration gestoppt oder teilweise abgeschlossen werden.
Fehler auf Netzwerkebene (TCP/Socket) ECONNRESET, ENOTFOUND, ESOCKETTIMEDOUT, ETIMEDOUT, ECONNREFUSED, EHOSTUNREACH, EPIPE und EAI_AGAIN. – Nein (wird von Adapter-Layer 2 verarbeitet) Der Adapter wird sofort wieder in die Warteschlange gestellt. Die Wiederherstellung erfolgt in der Regel schnell (Sekunden). Nachgelagerte Schritte können sich kurzzeitig verzögern.
Zeitüberschreitung auf Anwendungsebene HTTP timeout exceeded (keine Antwort erhalten). – Oft ja (Ebene 3) Nachgelagerte Schritte können sich verzögern, während Wiederholungsversuche auf Befehlsebene ausgeführt werden.

Beispiel mit minimaler generischer API-Konfiguration

Eine allgemeine API-Einrichtung für ein benutzerdefiniertes CRM mit den drei Endpunkten, die von der Kette verwendet werden: Kontakt suchen oder erstellen, Ticket suchen oder erstellen und Kommentar nach der Sitzung. Verwenden Sie diese als Ausgangspunkt und passen Sie sie an die Besonderheiten Ihres CRM-Systems an.

Einstellungen auf Instanzebene

{
  "lookup_method": "genericApi",
  "auth_method": "basic",
  "basic_auth_username": "ccai-integration",
  "basic_auth_password": "<secret>",
  "api_request_timeout": 10,
  "case_lookup_url": "https://crm.example.com/api/cases/{RECORD_ID}",
  "contact_lookup_url": "https://crm.example.com/api/contacts/{ACCOUNT_ID}",
  "skip_account_lookup": false,
  "skip_account_creation": false,
  "skip_record_creation": false
}

Antwortformen

Die Antwortform Ihres CRM ist kundenspezifisch. response_data_location ist ein Pfad im Lodash-Stil, der das relevante Objekt im geparsten Antworttext erreicht. Es ist nicht erforderlich, Antworten in ein übergeordnetes data-Feld einzuschließen. Die folgenden Beispiele zeigen standardmäßig realistische flache Formen.

Ein CRM, das Ressourcen unter data.contact verschachtelt, würde beispielsweise response_data_location: "data.contact" und einen Antworttext von { "contact": { "id": "c_99812" } } festlegen. Der Rest der Konfiguration bleibt unverändert.

Endpunkt 1 – contact_find_endpoint

Sucht einen Kontakt anhand der Telefonnummer oder E‑Mail-Adresse.

{
  "request_url": "https://crm.example.com/api/contacts/search?phone={PHONE_NUMBER}&email={EMAIL}",
  "request_method": "GET",
  "request_parameters": {},
  "response_data_location": "data"
}

Erfolgreich: Kontakt gefunden

200 OK
Content-Type: application/json
{ "id": "c_42018", "first_name": "Jane", "last_name": "Doe" }

Kontakt nicht gefunden

404 Not Found

Die Plattform behandelt 404 als „nicht gefunden“ (kein Fehler). Wenn skip_account_creation „false“ ist, wird der Ablauf mit contact_create_endpoint fortgesetzt.

Alternative für „Nicht gefunden“-Muster: ebenfalls gültig

200 OK
{}

Einige CRMs geben 200 OK mit leeren Daten anstelle von 404 zurück, wenn kein Datensatz übereinstimmt. Die Plattform behandelt beide gleich – beide lösen den nächsten Schritt aus (Erstellung, falls aktiviert).

Vorübergehender Fehler

503 Service Unavailable
}

Löst eine sofortige HTTP-Wiederholung auf Ebene 1 aus (insgesamt 2 Versuche). Wenn der Fehler weiterhin auftritt, wird auf die Wiederholungsversuche auf Befehlsebene von Ebene 3 zurückgegriffen.

Endpunkt 2: contact_create_endpoint

Erstellt einen Kontakt. Das Feld custom_id_location gibt der Plattform an, wo die ID des neuen Kontakts in der Antwort zu finden ist.

{
  "request_url": "https://crm.example.com/api/contacts",
  "request_method": "POST",
  "request_parameters": {
    "first_name": "{FIRST_NAME}",
    "last_name": "{LAST_NAME}",
    "email": "{EMAIL}",
    "phone": "{PHONE_NUMBER}",
    "external_session_id": "{SESSION_TYPE}-{SESSION_ID}"
  },
  "response_data_location": "data",
  "custom_id_location": "id"
}

Erfolgreich erstellt

201 Created
{ "id": "c_99812", "first_name": "John", "last_name": "Doe" }

2xx, aber fehlende ID am konfigurierten Speicherort

200 OK
{}

Der Endpunkt hat 200 OK ohne id am konfigurierten Speicherort zurückgegeben. Die Plattform protokolliert eine Warnung und leitet einen Null-contact_id-Wert weiter (keine Ausnahme ausgelöst, kein Wiederholungsversuch). Betrachten Sie dies als Konfigurationsfehler: response_data_location und custom_id_location sollten zuverlässig eine ID für jede 2xx liefern, die Ihr Endpunkt von diesem Pfad zurückgibt.

Endpunkt 3 – case_create_endpoint

Erstellt ein Ticket. Der contact_id aus dem vorherigen Schritt ist als {ACCOUNT_ID} verfügbar.

{
  "request_url": "https://crm.example.com/api/cases",
  "request_method": "POST",
  "request_parameters": {
    "subject": "{TICKET_SUBJECT}",
    "description": "{TICKET_DESCRIPTION}",
    "contact_id": "{ACCOUNT_ID}",
    "channel": "{CHANNEL}",
    "external_session_id": "{SESSION_TYPE}-{SESSION_ID}"
  },
  "response_data_location": "data",
  "custom_id_location": "id"
}

Erfolgreich erstellt

201 Created
{ "id": "case_77103", "status": "new" }

Mit response_data_location: "data" löst die Plattform den Pfad zum geparsten Antworttext auf. Anschließend wird das Feld unter custom_id_location: "id" → ticket_id = "case_77103" gelesen, das in die Phase nach der Sitzung einfließt.

Endpunkt 4: case_comment_endpoint

Dieser Endpunkt fügt dem Ticket nach dem Ende des Anrufs oder Chats einen Kommentar mit einer Zusammenfassung der Sitzung hinzu. Die Variable RECORD_ID enthält die in Schritt 3 erzeugte ticket_id.

{
  "request_url": "https://crm.example.com/api/cases/{RECORD_ID}/comments",
  "request_method": "POST",
  "request_parameters": {
    "body": "{COMMENT_BODY}",
    "agent_email": "{AGENT_EMAIL}",
    "channel": "{CHANNEL}",
    "duration": "{CALL_DURATION}",
    "external_session_id": "{SESSION_TYPE}-{SESSION_ID}"
  }
}

Bei generischen API-Instanzen mit konfiguriertem case_lookup_url wird dieser Endpunkt erst gesendet, wenn der Schritt zur Ticketerstellung erfolgreich abgeschlossen wurde. Ein fehlendes RECORD_ID bedeutet hier also ein Konfigurationsproblem und keinen vorübergehenden Zustand.

Variante: Kontoerstellung deaktiviert

Dieses Beispiel ähnelt dem vorherigen Beispiel für eine minimale generische API-Konfiguration, mit dem Unterschied, dass Ihre Instanz hier nicht das Erstellen von Kontakten im CRM zulässt. Die Kontosuche wird ausgeführt, die Kontoerstellung jedoch nicht.

Änderung der Instanzeinstellungen

{
  "skip_account_creation": true,
  "skip_account_lookup": false
}

Die Änderungen der Instanzeinstellungen umfassen die folgenden Verhaltensweisen:

  • Im Kontoschritt wird nur contact_find_endpoint aufgerufen. Wenn kein Kontakt gefunden wird, wird contact_create_endpoint nicht aufgerufen.

  • Der Aufzeichnungsschritt empfängt einen Nullwert für contact_id. Die Plattform fährt mit der Ticketerstellung ohne contact_id fort – {ACCOUNT_ID} wird als leer aufgelöst und das Feld contact_id wird vollständig aus der case_create_endpoint-Nutzlast entfernt.

  • Das bedeutet, dass Ihr Endpunkt für die Ticketerstellung in dieser Konfiguration Tickets ohne contact_id erstellen können muss. Wenn Ihr CRM für jedes Ticket einen zugehörigen Kontakt erfordert, ist diese Konfiguration nicht kompatibel.

Defensives Muster in case_create_endpoint

Ohne contact_id hat Ihr CRM weniger Kontext zum Anrufer als normalerweise. Mit dem =DEFAULT_VALUE-Hilfsprogramm können Sie alle in der Anfrage verfügbaren personenidentifizierbaren Informationen erfassen und als Fallback-Signal übergeben:

"request_parameters": {
  "subject": "{TICKET_SUBJECT}",
  "contact_id": "{ACCOUNT_ID}",
  "contact_origin": "=DEFAULT_VALUE(\"{EMAIL}\", \"{PHONE_NUMBER}\", \"anonymous\")"
}

Der =DEFAULT_VALUE-Helper wählt den ersten nicht leeren Wert aus. Ihr CRM erhält also eine E-Mail-Adresse oder Telefonnummer, wenn eine verfügbar ist, und den String "anonymous" nur, wenn beides nicht vorhanden ist. Das ist nützlich, um Tickets zu kennzeichnen, die keine identifizierenden Kontaktdaten enthalten.

Variante: Ticketablauf nur für die Suche (keine Datensatzerstellung)

Kontovorgänge werden normal ausgeführt, aber die Ticketerstellung ist deaktiviert. Bei der Integration werden Kommentare nur an vorhandene Tickets angehängt, die bei der Suche gefunden werden.

Änderung der Instanzeinstellungen

{
  "skip_record_creation": true,
  "case_lookup_url": "https://crm.example.com/api/cases/{RECORD_ID}"
}

Die Änderungen umfassen die folgenden Verhaltensweisen:

  • Im Aufzeichnungsschritt wird case_find_endpoint aufgerufen und das zurückgegebene Ticket verwendet. Wenn kein Ticket gefunden wird, wird die Kette beim Aufzeichnungsschritt beendet. case_create_endpoint wird nicht aufgerufen.

  • Endpunkte nach der Sitzung (case_comment_endpoint, case_update_endpoint und ähnliche) werden nur gesendet, wenn ein Ticket erfolgreich abgerufen wurde. Der Rails-seitige ready?-Guard sorgt dafür, dass diese Befehle in der Warteschlange bleiben (und schließlich ablaufen), wenn kein ticket_id materialisiert wird.

  • Praktische Auswirkung: In dieser Konfiguration erhalten Ihre Post-Session-Endpunkte nur Sitzungen, die mit einem bekannten Ticket verknüpft waren. Sie müssen den Zweig "missing ticket_id" nicht verarbeiten.

Die Plattform stellt sowohl SESSION_TYPE als auch SESSION_ID als Vorlagenvariablen bereit. Am einfachsten lässt sich das Muster für zusammengesetzte Schlüssel anwenden, indem Sie es direkt in jeden relevanten Anfragetext einfügen. Ihre Endpunkte haben dann den kanonischen Schlüssel, mit dem sie arbeiten können, ohne dass zusätzliche Logik auf Ihrer Seite erforderlich ist:

"request_parameters": {
  "...your fields...": "...",
  "ccai_session_key": "{SESSION_TYPE}-{SESSION_ID}"
}

Für denselben Aufruf wird bei jeder Wiederholung jedes Endpunkts in der Kette (Konto > Datensatz > Post-Session) dieselbe ccai_session_key erzeugt. Verwenden Sie sie als Deduplizierungsanker in der Erstellungs- oder Upsert-Logik Ihres CRM. Ein Upsert für (ccai_session_key, endpoint_kind) fängt beispielsweise Wiederholungsversuche sicher ab, ohne dass doppelte Datensätze entstehen.

Ausfallsichere Endpunkte erstellen (Idempotenz und Designtipps)

Da Anfragen wiederholt werden können (sofortige Wiederholung und Wiederholungen über mehrere Tage), sollten Ihre Endpunkte idempotent sein:

  • Verwenden Sie eine stabile zusammengesetzte Interaktions-ID als Idempotenzschlüssel:

    • Kombinieren Sie den Sitzungstyp mit der Sitzungs-ID, z. B. call-12345 oder chat-12345.

    • Verlassen Sie sich nicht nur auf call_id oder chat_id. Sprach- und Chat-IDs können sich überschneiden, da jede Sequenz bei 1 beginnen kann.

  • Wenn du eine Anfrage erhältst, die ein Duplikat zu sein scheint:

    • Prüfen Sie die Nutzlast, um festzustellen, ob es sich tatsächlich um ein Duplikat handelt. Einige freigegebene Endpunkte, z. B. Kommentar- oder Notizendpunkte, können von mehreren Befehlstypen verwendet werden.

    • Bei Erstellungsvorgängen sollten unter normalen, erfolgreichen Bedingungen keine doppelten Anfragen auftreten. Sie können jedoch auftreten, wenn das CRM die Anfrage verarbeitet und dann einen Fehler zurückgegeben hat oder eine Zeitüberschreitung aufgetreten ist, bevor die Plattform eine erfolgreiche Antwort erhalten hat.

    • Wenn eine doppelte Erstellungsanfrage bestätigt wird, geben Sie die zuvor erstellte Datensatz-ID anstelle eines anderen Datensatzes zurück.

  • Fehlende IDs explizit verarbeiten:

    • Ein fehlendes contact_id bei der Ticketerstellung weist in der Regel auf eine Konfiguration hin, bei der die Kontosuche oder die Kontoerstellung deaktiviert ist. Wenn für Ihre Instanz Konten erforderlich sind, sollten Sie das Problem untersuchen, anstatt Tickets ohne Kontakte zu erstellen.

    • Ein fehlender ticket_id bei Aufrufen nach der Sitzung ist bei typischen generischen API-Einrichtungen, bei denen die Ticket-Suche konfiguriert ist, nicht zu erwarten. Prüfen Sie die Konfiguration der Ticket-Suche und die Nutzlastvorlagen, bevor Sie die Anfrage als normale No-Op-Anfrage behandeln.

  • Bei Aktualisierungen sollten Sie Felder auf bestimmte Werte setzen, anstatt Zähler zu erhöhen, damit wiederholte Aufrufe sicher sind.

Fehlerbehebung und Beobachtbarkeit

Beachten Sie beim Debuggen einer benutzerdefinierten CRM-Integration die folgenden Muster:

  • Wiederholte Aufrufe desselben Endpunkts:

    • Vergleichen Sie die Zeitstempel mit dem Wiederholungszeitplan unter Wiederholungen auf Befehlsebene (~7 Tage, 14 Versuche).

    • Korrelieren Sie Ereignisse mithilfe der zusammengesetzten Sitzungskennung, z. B. Sitzungstyp + Anruf- oder Chatsitzungs-ID.

    • In den exportierten Logs der CCAI Platform können die Anruf- oder Chatsitzungs-ID zusammen mit API-Ereignissen angezeigt werden, um die Nachverfolgbarkeit zu verbessern.

    • Prüfen Sie, ob Ihr Endpunkt konsistent einen Fehler zurückgibt, der wiederholt werden kann (z. B. 500), anstatt eines nicht wiederholbaren Konfigurationsfehlers.

  • Wiederholungsversuche, die „nicht aufhören“:

    • Prüfen Sie die Fehlerantworten, die Ihr Endpunkt zurückgibt.

    • Wenn Sie einen dauerhaften Fehler beabsichtigt haben, wenden Sie sich an den Support, um zu erfahren, wie Sie einen nicht wiederholbaren Fehler für Ihre Konfiguration angeben können.

  • Endpunkt wurde nie aufgerufen:

    • Überprüfen Sie Folgendes:

      • Die vorgelagerten Schritte (Konto/Eintrag) wurden erfolgreich abgeschlossen und die erforderlichen IDs wurden erstellt.

      • Der Endpunkt ist in Ihren benutzerdefinierten CRM-Einstellungen richtig konfiguriert und aktiviert.

    • Ein falsch konfigurierter oder deaktivierter Endpunkt oder ein Fehler weiter oben in der Kette kann verhindern, dass bestimmte Schritte ausgeführt werden.

  • Logs korrelieren:

    • Protokollieren Sie die vollständige Anfrage und Antwort auf Ihrer Seite, einschließlich der Interaktions-ID (call_id / chat_id).

    • Verwenden Sie diese ID, um Ihre CRM-Logs mit dem Verhalten der Plattform im Laufe der Zeit (insbesondere bei Wiederholungsversuchen) zu korrelieren.