Gestione degli errori, nuovi tentativi e ordine delle chiamate nel CRM personalizzato (API generica)

Questo documento descrive il comportamento della funzionalità CRM personalizzato (API generica) della piattaforma CCAI quando gli endpoint CRM restituiscono risposte diverse da HTTP 200 "Success.". È destinato a fungere da riferimento per il comportamento degli integratori che configurano gli endpoint dell'account API e dei record API.

Ordine di esecuzione e relazioni di alto livello

Quando un'interazione attiva un'integrazione CRM personalizzata, la piattaforma chiama i tuoi endpoint in questo ordine:

  1. Operazioni a livello di account (account API) - contatto

    Esempi:

    • Trova un contatto.

    • Crea un contatto.

    • Aggiorna un contatto.

  2. Operazioni a livello di record (record API): ticket o richiesta

    Esempi:

    • Trova un biglietto.

    • Crea un ticket.

    • Aggiorna un ticket.

  3. Azioni post-sessione (se configurate)

    Esempi:

    • Aggiungi un commento o una nota.

    • Carica un allegato o una trascrizione.

    • Applica gli aggiornamenti di chiusura.

I passaggi precedenti in genere producono ID che i passaggi successivi possono utilizzare. Ad esempio, un contact_id può essere passato alla creazione del ticket se incluso nel modello di payload dell'endpoint e un ticket_id è richiesto per le azioni post-sessione nelle configurazioni API generiche tipiche. Tieni presente che non tutti gli endpoint sono configurati per estrarre un ID. Consulta Sfumatura importante: 2xx + ID mancante sugli endpoint di estrazione dell'ID.

Sfumatura importante: 2xx + ID mancante sugli endpoint di estrazione degli ID

Non tutti gli endpoint CRM personalizzati estraggono un ID dalla risposta che ricevono. Questo comportamento si applica solo agli endpoint configurati con un response_data_location e (per gli endpoint di creazione) un custom_id_location, in genere endpoint di ricerca (estrazione dell'ID di un record esistente) ed endpoint di creazione (estrazione dell'ID di un record appena creato). Gli endpoint come commenti, allegati e aggiornamenti non estraggono gli ID dalle loro risposte.

Impatto dell'ID mancante sugli endpoint di estrazione degli ID

  • Per gli endpoint di ricerca: una risposta 200 OK senza record corrispondente (e quindi senza ID estraibile) è un comportamento normale di "non trovato". Se l'istanza ha skip_account_creation o skip_record_creation abilitato, la piattaforma procederà intenzionalmente a valle con un valore contact_id o ticket_id nullo anziché tentare la creazione. Si tratta di un comportamento previsto in queste configurazioni e non di un errore di configurazione.

  • Per gli endpoint di creazione: una risposta 200 OK che non include l'ID appena creato nella posizione configurata è un problema di configurazione o di contratto di risposta. La richiesta HTTP è andata a buon fine, quindi non verranno attivati nuovi tentativi, ma i passaggi a valle potrebbero procedere con dati mancanti.

  • In entrambi i casi, l'errore (se si tratta di un errore) viene visualizzato come dati mancanti anziché come errore dell'endpoint, il che può creare confusione durante il debug.

Guida per gli integratori

  • Per le operazioni di creazione, assicurati che la restituzione dell'ID previsto nella posizione configurata faccia parte del contratto di esito positivo, non solo la restituzione di 2xx. Considera un ID mancante come un problema di configurazione o di contratto di risposta che vale la pena esaminare.

  • Per le operazioni di ricerca, è accettabile restituire 200 OK senza corrispondenza. Se la tua istanza si basa intenzionalmente su pattern di "ricerca senza creazione" (ad esempio, skip_account_creation = true), documenta questa decisione in modo che gli endpoint downstream sappiano come gestire correttamente gli ID mancanti.

  • Durante i test, verifica che:

    • Per gli endpoint di creazione, l'ID è presente in modo affidabile nella risposta e nella posizione esatta configurata nel CRM personalizzato.

    • Per gli endpoint di ricerca, il comportamento downstream della piattaforma corrisponde alla configurazione del flag di salto dell'istanza.

Gestione degli errori: panoramica

Quando un endpoint restituisce una risposta non riuscita (non 2xx) o non risponde:

  • La piattaforma potrebbe riprovare a inviare la richiesta:

    • Una volta immediatamente per alcuni stati.

    • Per un periodo più lungo per gli errori per cui è possibile riprovare.

  • I passaggi downstream potrebbero subire ritardi mentre la piattaforma continua a riprovare un passaggio upstream.

  • Alcuni errori vengono trattati come non ripetibili (ad esempio, errori di configurazione o convalida).

Le regole dettagliate per i nuovi tentativi sono descritte in Comportamento di ripetizione e backoff. La relazione tra gli errori e le chiamate downstream è descritta in Regole di concatenamento e dipendenza.

Regole di concatenamento e dipendenza

Il comportamento personalizzato del CRM è regolato dalla configurazione del CRM della tua istanza, in particolare dalle impostazioni documentate in Salta la creazione di account e record CRM. Questo documento fa riferimento a queste impostazioni con i nomi di configurazione del backend (skip_account_creation, skip_account_lookup, skip_record_creation) poiché vengono visualizzati in questo modo negli esempi di configurazione JSON riportati di seguito.

Nell'ambito di queste impostazioni, la piattaforma è orientata a continuare la catena quando può, ad esempio creando un contatto anonimo quando la ricerca non va a buon fine e la creazione dell'account è abilitata, anziché "interrompersi" sempre.

Impatto degli errori dell'account sulle operazioni di registrazione

Il passaggio di registrazione (ticket/richiesta) può essere eseguito anche se il passaggio dell'account non produce un contatto, ma il comportamento esatto dipende dalla configurazione dell'istanza.

A seconda della configurazione, la piattaforma può:

  • Crea un contatto anonimo come opzione di riserva e continua con la creazione del ticket.

  • Procedi con i passaggi di registrazione senza un contact_id quando la ricerca o la creazione dell'account sono configurate per essere ignorate.

Cosa comporta per i tuoi endpoint

  • L'assenza di contact_id al momento della creazione del ticket di solito indica una configurazione dell'istanza in cui la ricerca o la creazione dell'account è disabilitata.

  • Se la tua istanza richiede account, considera l'assenza di contact_id come un segnale che vale la pena esaminare, anziché inserire ticket in modo silenzioso senza un contatto.

  • Se la tua configurazione consente intenzionalmente la creazione di ticket senza un contatto, assicurati che l'endpoint del ticket gestisca questo caso in modo esplicito e prevedibile.

Impatto degli errori di registrazione sulle azioni post-sessione

Per le configurazioni API generiche in cui è configurata la ricerca dei ticket, la piattaforma non invia chiamate post-sessione, come call_finished, chat_finished, email_finished, save_call_recording, save_chat_history, update_ticket e done_ticket, finché non esiste un ticket_id.

Se un endpoint post-sessione viene richiamato senza un ticket_id, di solito indica una delle seguenti condizioni:

  • La ricerca dei ticket è disabilitata per la configurazione dell'istanza, il che è insolito per una tipica configurazione dell'API generica.

  • Il template del payload ha omesso la variabile ticket_id, un problema di configurazione che vale la pena esaminare.

Cosa comporta per i tuoi endpoint

  • Considera l'assenza di ticket_id nelle chiamate post-sessione come un segnale di configurazione che vale la pena esaminare, non come un comportamento previsto da accettare senza intervenire.

  • Se la tua configurazione non richiede intenzionalmente la ricerca dei ticket, configura gli endpoint post-sessione in modo che gestiscano correttamente un ticket_id mancante. Ad esempio, registra il problema e l'operazione no-op o restituisci un messaggio di errore chiaro e ben strutturato anziché causare un arresto anomalo.

Comportamento di nuovo tentativo e backoff

I nuovi tentativi vengono eseguiti su tre livelli:

  1. Nuovo tentativo immediato a livello HTTP (un secondo tentativo rapido).

  2. Nuovo tentativo a livello di adattatore (recupero rapido per errori di rete e risposte temporanee specifiche).

  3. Tentativi ripetuti a livello di comando (tentativi ripetuti di coda lunga nell'arco di giorni).

Nuovo tentativo immediato a livello HTTP (nuovo tentativo rapido)

Per alcuni stati temporanei, la piattaforma effettua fino a 2 tentativi in totale (1 tentativo iniziale + 1 nuovo tentativo immediato). In genere, questo vale per i seguenti stati di errore:

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

Nuovo tentativo a livello di adattatore (recupero rapido della rete)

Tra la chiamata HTTP e la pianificazione a livello di comando, un livello di nuovo tentativo intermedio nell'adattatore CRM (command_runner.js) gestisce gli errori che non producono affatto una risposta HTTP o che corrispondono a messaggi temporanei specifici:

  • Reinserimento immediato in coda: attivato da errori a livello di TCP/socket: ECONNRESET, ENOTFOUND, ESOCKETTIMEDOUT, ETIMEDOUT, ECONNREFUSED, EHOSTUNREACH, EPIPE, EAI_AGAIN. Si tratta di errori di rete che si verificano prima della ricezione di una risposta HTTP.

  • Nuovo tentativo ritardato di 30 secondi: attivato quando il messaggio di errore è "Too Early" (HTTP 425), "Service Unavailable" o "Unordered Collection".

  • Non ripetibile a questo livello: tutto il resto viene gestito dalla pianificazione dei nuovi tentativi a livello di comando (Livello 3).

Perché è importante per gli integratori

Questi errori si verificano quando la piattaforma non riesce a stabilire o mantenere una connessione TCP al tuo endpoint, il che significa che spesso indicano un problema sul tuo server (server inattivo, rifiuto delle connessioni o interruzione della connessione a metà della richiesta), non solo nell'infrastruttura interna. L'effetto pratico è che alcuni errori di rete vengono risolti molto più velocemente rispetto alla pianificazione di 7 giorni a livello di comando, spesso in pochi secondi.

Tentativi ripetuti a livello di comando (~7 giorni, 14 tentativi)

Se un'operazione non va a buon fine e può essere ripetuta, la piattaforma potrebbe riprovare fino a 14 volte nell'arco di circa 7 giorni, utilizzando questa pianificazione:

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

Questo comportamento di ripetizione long-tail può essere applicato a:

  • Operazioni relative all'account.

  • Registra le operazioni.

  • Operazioni post-sessione.

Errori non ripetibili

Alcuni errori vengono trattati come non ripetibili, ad esempio:

  • Errori di configurazione o convalida (ad esempio, gli endpoint richiesti non sono configurati o sono configurati in modo errato).

  • Alcune categorie di errori interni rilevate dalla piattaforma.

Se devi assicurarti che un errore venga trattato come permanente (senza nuovi tentativi), contatta l'assistenza o il team di implementazione per confermare il modo corretto di indicare un errore non ripetibile nella tua configurazione specifica.

Timeout ed errori di rete

La piattaforma gestisce due percorsi distinti:

  1. Timeout a livello di applicazione: quando viene superato il timeout HTTP configurato (la richiesta è stata inviata, ma non è stata ricevuta alcuna risposta), la piattaforma genera un errore interno che può essere ritentato a livello di comando (livello 3). Ciò significa che la richiesta segue la pianificazione di backoff standard (fino a 14 nuovi tentativi in circa 7 giorni).

  2. Errori a livello di socket/TCP: quando la connessione non riesce a livello di rete prima della ricezione di una risposta HTTP (ad esempio ETIMEDOUT, ESOCKETTIMEDOUT e ECONNREFUSED), il livello dell'adattatore (livello 2) li rileva e mette immediatamente in coda il comando. Il ripristino da questi errori è in genere molto più rapido, spesso entro pochi secondi anziché seguire la pianificazione di 7 giorni.

Perché la distinzione è importante

  • Un timeout dell'applicazione (il tuo server ha accettato la connessione, ma non ha risposto in tempo) riprova più lentamente.

  • Un errore a livello di rete (il tuo server non è stato raggiunto affatto) viene riprovato molto più rapidamente.

  • In entrambi i casi, la richiesta potrebbe essere stata elaborata parzialmente, pertanto gli endpoint devono essere idempotenti. Consulta Creazione di endpoint resilienti (idempotenza e suggerimenti per la progettazione).

Matrice del comportamento del codice di stato e del timeout (con esempi)

Le tabelle e gli esempi seguenti descrivono in che modo la piattaforma CCAI gestisce i diversi codici di stato HTTP, i timeout e gli errori di rete.

Tabella di riepilogo dei risultati

Le righe relative agli ID nella tabella seguente si applicano solo agli endpoint configurati per estrarre un ID dalla risposta, ad esempio gli endpoint di ricerca o di creazione. La maggior parte degli altri endpoint non esegue l'estrazione dell'ID risposta.

Risultato Esempi Nuovo tentativo HTTP immediato? Tentativi di ripetizione a lungo termine (~7 giorni)? Impatto downstream
Operazione riuscita per un endpoint di estrazione degli ID 2xx + ID previsto presente nella posizione della risposta configurata. No No Il downstream procede con l'ID estratto.
Ricerca senza corrispondenza 2xx, ma non è stato trovato alcun record nella posizione configurata. No No Normale comportamento "non trovato". Con skip_account_creation o skip_record_creation abilitati, i sistemi downstream procedono intenzionalmente con ID nulli.
Crea 2xx di ritorno senza un ID 2xx da un endpoint di creazione, ma l'ID del nuovo record non è presente nella posizione configurata. No No La fase downstream potrebbe procedere con dati mancanti. Trattalo come un problema di configurazione o di contratto di risposta.
Esito positivo da un endpoint che non estrae ID 2xx da endpoint come azioni di nota, aggiornamento o allegato che non estraggono ID. No No Il downstream procede in base alla catena di comandi e alla configurazione dell'istanza.
Errore temporaneo 408, 413, 429, 500, 502, 503, 504, 521, 522 e 524. Sì (due tentativi in totale) Spesso sì I passaggi downstream potrebbero essere ritardati durante i nuovi tentativi.
Altri errori 400, 401, 403, 404 e altri 4xx/5xx. No Spesso sì I passaggi downstream potrebbero essere ritardati durante i nuovi tentativi.
Errore di configurazione/convalida configurazione errata, endpoint mancanti. N/D No La catena potrebbe interrompersi o essere completata parzialmente a seconda della configurazione.
Errore a livello di rete (TCP/socket) ECONNRESET, ENOTFOUND, ESOCKETTIMEDOUT, ETIMEDOUT, ECONNREFUSED, EHOSTUNREACH, EPIPE e EAI_AGAIN. N/D No (gestito dall'adattatore di livello 2) L'adattatore viene immediatamente rimesso in coda; il ripristino è in genere rapido (secondi). I passaggi a valle potrebbero subire un breve ritardo.
Timeout a livello di applicazione HTTP timeout exceeded (nessuna risposta ricevuta). N/D Spesso sì (livello 3) I passaggi downstream potrebbero essere ritardati durante i nuovi tentativi a livello di comando.

Esempio pratico con configurazione minima dell'API generica

Una configurazione API generica di base del CRM personalizzato con i tre endpoint utilizzati dalla catena: trova o crea contatto, trova o crea ticket e un commento post-sessione. Utilizzalo come punto di partenza e adattalo alle specifiche del tuo CRM.

Impostazioni a livello di istanza

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

Forme di risposta

La forma della risposta del CRM è specifica per il cliente. response_data_location è un percorso in stile lodash che raggiunge l'oggetto pertinente all'interno del corpo della risposta analizzata. Non è necessario inserire le risposte in un campo data di primo livello. I seguenti esempi mostrano forme piatte realistiche per impostazione predefinita.

Ad esempio, un CRM che nidifica le risorse in data.contact imposta response_data_location: "data.contact" e un corpo della risposta di { "contact": { "id": "c_99812" } }; il resto della configurazione rimane invariato.

Endpoint 1 - contact_find_endpoint

Cerca un contatto per numero di telefono o email.

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

Operazione riuscita: contatto trovato

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

Contatto non trovato

404 Not Found

La piattaforma considera 404 come "non trovato" (non un errore). Se skip_account_creation è false, il flusso procede con contact_create_endpoint.

Pattern alternativo non trovato: valido anche questo

200 OK
{}

Alcuni CRM restituiscono 200 OK con dati vuoti anziché 404 quando non ci sono record corrispondenti. La piattaforma gestisce entrambi i casi allo stesso modo: entrambi attivano il passaggio successivo (creazione, se abilitata).

Errore temporaneo

503 Service Unavailable
}

Attiva un nuovo tentativo HTTP immediato di livello 1 (2 tentativi totali). Se l'errore persiste, passa ai nuovi tentativi a livello di comando del livello 3.

Endpoint 2 - contact_create_endpoint

Crea un contatto. Il campo custom_id_location indica alla piattaforma dove trovare l'ID del nuovo contatto all'interno della risposta.

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

Creazione riuscita

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

2xx, ma manca l'ID nella posizione configurata

200 OK
{}

L'endpoint ha restituito 200 OK senza id nella posizione configurata. La piattaforma registra un avviso e inoltra un valore contact_id null a valle (non viene generata alcuna eccezione, nessun nuovo tentativo). Considera questo un problema di configurazione: response_data_location e custom_id_location dovrebbero restituire in modo affidabile un ID per qualsiasi 2xx restituito dall'endpoint da questo percorso.

Endpoint 3 - case_create_endpoint

Crea un ticket. Il contact_id del passaggio precedente è disponibile come {ACCOUNT_ID}.

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

Creazione riuscita

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

Con response_data_location: "data", la piattaforma risolve il percorso del corpo della risposta analizzata. Poi legge il campo in custom_id_location: "id" → ticket_id = "case_77103", che passa alla post-sessione.

Endpoint 4 - case_comment_endpoint

Questo endpoint aggiunge un commento di riepilogo della sessione al ticket al termine della chiamata o della chat. La variabile RECORD_ID contiene il valore ticket_id prodotto dal passaggio 3.

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

Per le istanze API generiche con case_lookup_url configurato, la piattaforma non invierà questo endpoint finché il passaggio di creazione del ticket non sarà completato correttamente, pertanto la mancanza di RECORD_ID qui indica un problema di configurazione, non uno stato temporaneo.

Variante: creazione dell'account disattivata

Questo esempio è molto simile a quello precedente per una configurazione minima dell'API generica, con la differenza che qui l'istanza non consente la creazione di contatti nel CRM. Mentre la ricerca dell'account viene eseguita, la creazione non viene eseguita.

Modifica delle impostazioni dell'istanza

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

Le modifiche alle impostazioni dell'istanza includono i seguenti comportamenti:

  • Il passaggio dell'account chiama solo contact_find_endpoint. Se non viene trovato alcun contatto, non chiama contact_create_endpoint.

  • Il passaggio di registrazione riceve un valore null contact_id. La piattaforma procede alla creazione del ticket senza un contact_id: {ACCOUNT_ID} viene risolto in un valore vuoto e il campo contact_id viene rimosso completamente dal payload case_create_endpoint.

  • Ciò significa che l'endpoint di creazione dei ticket deve essere in grado di creare ticket senza un contact_id in questa configurazione. Se il tuo CRM richiede un contatto associato per ogni ticket, questa configurazione non è compatibile.

Pattern difensivo in case_create_endpoint

Senza un contact_id, il tuo CRM ha meno contesto sul chiamante rispetto a quello che avrebbe normalmente. Puoi utilizzare l'helper =DEFAULT_VALUE per acquisire tutte le informazioni identitarie disponibili nella richiesta e trasmetterle come indicatore di riserva:

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

L'helper =DEFAULT_VALUE sceglie il primo valore non vuoto, in modo che il tuo CRM riceva un indirizzo email o un numero di telefono quando è disponibile e la stringa letterale "anonymous" solo quando non è disponibile, il che è utile per segnalare i ticket a cui non sono allegati dati di contatto identificativi.

Variante: flusso di ticket di sola ricerca (nessuna creazione di record)

Le operazioni dell'account vengono eseguite normalmente, ma la creazione dei ticket è disabilitata. L'integrazione allega i commenti solo ai ticket esistenti visualizzati dalla ricerca.

Modifica delle impostazioni dell'istanza

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

Le modifiche riguardano i seguenti comportamenti:

  • Il passaggio di registrazione chiama case_find_endpoint e utilizza il ticket restituito. Se non viene trovato alcun ticket, la catena si interrompe al passaggio di registrazione e case_create_endpoint non viene richiamato.

  • Gli endpoint post-sessione (case_comment_endpoint, case_update_endpoint e simili) vengono inviati solo quando un biglietto è stato cercato correttamente. La protezione ready? lato Rails garantisce che questi comandi rimangano in coda (e alla fine scadano) se non viene mai materializzato alcun ticket_id.

  • Implicazione pratica: in questa configurazione, gli endpoint post-sessione riceveranno solo le sessioni associate a un ticket noto. Non è necessario gestire il ramo "missing ticket_id".

La piattaforma espone sia SESSION_TYPE sia SESSION_ID come variabili del modello. Il modo più pulito per applicare il pattern della chiave composita è inserirlo direttamente in ogni corpo della richiesta pertinente. In questo modo, i tuoi endpoint avranno la chiave canonica con cui lavorare, senza logica aggiuntiva da parte tua:

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

Per la stessa chiamata, ogni nuovo tentativo di ogni endpoint della catena (account > record > post-sessione) produrrà lo stesso ccai_session_key. Utilizzalo come ancoraggio di deduplicazione nella logica di creazione o upsert del tuo CRM. Ad esempio, un upsert su (ccai_session_key, endpoint_kind) assorbirà in modo sicuro i nuovi tentativi senza produrre record duplicati.

Creazione di endpoint resilienti (idempotenza e suggerimenti di progettazione)

Poiché le richieste possono essere ripetute (nuovo tentativo immediato + nuovi tentativi nel corso dei giorni), i tuoi endpoint devono essere idempotenti:

  • Utilizza un identificatore di interazione composito stabile come chiave di idempotenza:

    • Combina il tipo di sessione con l'ID sessione, ad esempio call-12345 o chat-12345.

    • Non fare affidamento solo su call_id o chat_id. Gli ID delle chat e delle chiamate vocali possono sovrapporsi perché ogni sequenza può iniziare da 1.

  • Se ricevi una richiesta che sembra essere un duplicato:

    • Esamina il payload per determinare se si tratta effettivamente di un duplicato. Alcuni endpoint condivisi, come quelli per i commenti o le note, possono essere utilizzati da più tipi di comandi.

    • Per le operazioni di creazione, le richieste duplicate non dovrebbero verificarsi in condizioni normali di esito positivo, ma possono verificarsi se il CRM ha elaborato la richiesta e poi ha restituito un errore o un timeout prima che la piattaforma ricevesse una risposta positiva.

    • Quando viene confermata una richiesta di creazione duplicata, restituisci l'ID del record creato in precedenza anziché un altro record.

  • Gestisci esplicitamente gli ID mancanti:

    • L'assenza di contact_id al momento della creazione del ticket di solito indica una configurazione in cui la ricerca o la creazione dell'account è disabilitata. Se la tua istanza richiede account, esaminala invece di creare ticket senza contatti.

    • Un ticket_id mancante nelle chiamate post-sessione non è previsto per le configurazioni tipiche delle API generiche in cui è configurata la ricerca dei ticket. Controlla la configurazione della ricerca dei ticket e i modelli di payload prima di trattare la richiesta come una normale operazione senza effetto.

  • Per gli aggiornamenti, preferisci l'impostazione dei campi su valori specifici anziché l'incremento dei contatori, in modo che le chiamate ripetute siano sicure.

Risoluzione dei problemi e osservabilità

Quando esegui il debug di un'integrazione CRM personalizzata, tieni presente questi pattern:

  • Chiamate ripetute allo stesso endpoint:

    • Confronta i timestamp con la pianificazione dei nuovi tentativi in Nuovi tentativi a livello di comando (~7 giorni, 14 tentativi).

    • Correlare gli eventi utilizzando l'identificatore di sessione composito, ad esempio tipo di sessione + ID sessione di chiamata o chat.

    • I log esportati di CCAI Platform possono aiutare a mostrare l'ID sessione di chiamata o chat insieme agli eventi API per la tracciabilità.

    • Verifica se l'endpoint restituisce costantemente un errore per cui è possibile riprovare (ad esempio 500) anziché un errore di configurazione per cui non è possibile riprovare.

  • Tentativi di ripetizione che "non si fermano":

    • Esamina le risposte di errore restituite dall'endpoint.

    • Se l'errore è permanente, contatta l'assistenza per ricevere indicazioni su come indicare un errore non ripetibile per la tua configurazione.

  • L'endpoint non è mai stato chiamato:

    • Verifica quanto segue:

      • I passaggi upstream (account/record) sono stati completati correttamente e hanno generato gli ID necessari.

      • L'endpoint è configurato e attivato correttamente nelle impostazioni del CRM personalizzato.

    • Un endpoint configurato in modo errato o disabilitato o un errore precedente nella catena può impedire l'esecuzione di determinati passaggi.

  • Correlazione dei log:

    • Registra la richiesta e la risposta complete sul tuo lato, incluso l'ID interazione (call_id/chat_id).

    • Utilizza questo ID per correlare i log del CRM con il comportamento della piattaforma nel tempo (soprattutto durante i nuovi tentativi).