Gestion des exceptions, nouvelles tentatives et ordre des appels dans un CRM personnalisé (API générique)

Ce document décrit le comportement de la fonctionnalité de CRM personnalisé (API générique) de CCAI Platform lorsque vos points de terminaison CRM renvoient des réponses autres que HTTP 200 "Success.". Il sert de référence de comportement pour les intégrateurs qui configurent les points de terminaison de compte d'API et d'enregistrement d'API.

Ordre d'exécution et relations de haut niveau

Lorsqu'une interaction déclenche une intégration de CRM personnalisée, la plate-forme appelle vos points de terminaison dans l'ordre suivant :

  1. Opérations au niveau du compte (compte API) : contact

    Exemples :

    • Rechercher un contact

    • Créez un contact.

    • Mettre à jour un contact

  2. Opérations au niveau des enregistrements (enregistrement d'API) : ticket ou demande d'assistance

    Exemples :

    • Recherchez un billet.

    • Créer une demande d'assistance

    • Mettre à jour une demande

  3. Actions post-session (si configurées)

    Exemples :

    • Ajoutez un commentaire ou une note.

    • Importez une pièce jointe ou une transcription.

    • Appliquez les mises à jour de finalisation.

Les étapes précédentes produisent généralement des ID que les étapes ultérieures peuvent utiliser. Par exemple, un contact_id peut être transmis à la création de tickets lorsqu'il est inclus dans votre modèle de charge utile de point de terminaison, et un ticket_id est requis pour les actions post-session dans les configurations d'API génériques types. Notez que tous les points de terminaison ne sont pas configurés pour extraire un ID. Consultez Nuance importante : 2xx + ID manquant sur les points de terminaison d'extraction d'ID.

Nuance importante : 2xx + ID manquant sur les points de terminaison d'extraction d'ID

Tous les points de terminaison CRM personnalisés n'extraient pas un ID de la réponse qu'ils reçoivent. Ce comportement ne s'applique qu'aux points de terminaison configurés avec un response_data_location et (pour les points de terminaison de création) un custom_id_location, généralement des points de terminaison de recherche (extraction de l'ID d'un enregistrement existant) et des points de terminaison de création (extraction de l'ID d'un enregistrement nouvellement créé). Les points de terminaison tels que les commentaires, les pièces jointes et les mises à jour n'extraient pas les ID de leurs réponses.

Impact de l'absence d'ID sur les points de terminaison d'extraction d'ID

  • Pour les points de terminaison de recherche : une réponse 200 OK sans enregistrement correspondant (et donc sans ID extractible) est un comportement normal de type "introuvable". Si skip_account_creation ou skip_record_creation est activé sur votre instance, la plate-forme continuera intentionnellement en aval avec une valeur contact_id ou ticket_id nulle plutôt que de tenter de créer l'instance. Ce comportement est normal dans ces configurations et ne constitue pas une erreur de configuration.

  • Pour les points de terminaison de création : une réponse 200 OK qui n'inclut pas l'ID nouvellement créé à l'emplacement configuré est un problème de configuration ou de contrat de réponse. La requête HTTP a abouti, donc aucune nouvelle tentative ne sera déclenchée, mais les étapes en aval peuvent se poursuivre avec des données manquantes.

  • Dans les deux cas, l'échec (lorsqu'il s'agit d'un échec) apparaît comme des données manquantes plutôt que comme une erreur de point de terminaison, ce qui peut prêter à confusion lors du débogage.

Conseils pour les intégrateurs

  • Pour les opérations de création, assurez-vous que le renvoi de l'ID attendu à l'emplacement configuré fait partie de votre contrat de réussite, et pas seulement le renvoi de 2xx. Traitez un ID manquant comme un problème de configuration ou de contrat de réponse qui mérite d'être examiné.

  • Pour les opérations de recherche, il est acceptable de renvoyer 200 OK sans correspondance. Si votre instance repose intentionnellement sur des modèles de "recherche sans création" (par exemple, skip_account_creation = true), documentez cette décision afin que les points de terminaison en aval sachent comment gérer correctement les ID manquants.

  • Lors des tests, vérifiez les points suivants :

    • Pour les points de terminaison de création, l'ID est toujours présent dans la réponse et à l'emplacement exact configuré dans le CRM personnalisé.

    • Pour les points de terminaison de recherche, le comportement en aval de la plate-forme correspond à la configuration de l'indicateur d'omission de votre instance.

Gestion des exceptions : présentation

Lorsqu'un point de terminaison renvoie une réponse d'échec (autre que 2xx) ou ne répond pas :

  • La plate-forme peut réessayer d'envoyer la requête :

    • Une fois immédiatement pour certains états.

    • Sur une période plus longue pour les échecs pouvant être relancés.

  • Les étapes en aval peuvent être retardées pendant que la plate-forme continue de réessayer une étape en amont.

  • Certains échecs sont traités comme non renouvelables (par exemple, les échecs de configuration ou de validation).

Les règles de nouvelle tentative détaillées sont décrites dans la section Comportement de nouvelle tentative et d'intervalle exponentiel entre les tentatives. La relation entre les échecs et les appels en aval est décrite dans la section Règles de chaînage et de dépendance.

Règles de chaînage et de dépendance

Le comportement du CRM personnalisé est régi par la configuration du CRM de votre instance, en particulier les paramètres décrits dans Ignorer la création de comptes et d'enregistrements CRM. Ce document fait référence à ces paramètres par leurs noms de configuration de backend (skip_account_creation, skip_account_lookup, skip_record_creation), car ils apparaissent ainsi dans les exemples de configuration JSON suivants.

Dans ces paramètres, la plate-forme est biaisée pour continuer la chaîne lorsqu'elle le peut (par exemple, en créant un contact anonyme lorsque la recherche échoue et que la création de compte est activée) plutôt que de toujours "arrêter".

Impact des défaillances de compte sur les opérations d'enregistrement

L'étape d'enregistrement (ticket/demande) peut s'exécuter même si l'étape de compte ne produit pas de contact, mais le comportement exact dépend de la configuration de l'instance.

Selon votre configuration, la plate-forme peut :

  • Créez un contact anonyme comme solution de secours et poursuivez la création du ticket.

  • Passez aux étapes d'enregistrement sans contact_id lorsque la recherche ou la création de compte sont configurées pour être ignorées.

Qu'est-ce que cela signifie pour vos points de terminaison ?

  • L'absence de contact_id lors de la création d'un ticket indique généralement une configuration d'instance dans laquelle la recherche ou la création de compte est désactivée.

  • Si votre instance nécessite des comptes, considérez l'absence de contact_id comme un signal méritant d'être examiné, plutôt que d'insérer silencieusement des tickets sans contact.

  • Si votre configuration autorise intentionnellement la création de demandes sans contact, assurez-vous que votre point de terminaison de demande gère ce cas de manière explicite et prévisible.

Impact des échecs d'enregistrement sur les actions après la session

Pour les configurations d'API génériques où la recherche de tickets est configurée, la plate-forme n'envoie pas d'appels post-session (tels que call_finished, chat_finished, email_finished, save_call_recording, save_chat_history, update_ticket et done_ticket) tant qu'un ticket_id n'existe pas.

Si un point de terminaison post-session est appelé sans ticket_id, cela indique généralement l'une des conditions suivantes :

  • La recherche de tickets est désactivée pour la configuration de l'instance, ce qui est inhabituel pour une configuration d'API générique classique.

  • Le modèle de charge utile a omis la variable ticket_id, ce qui constitue un problème de configuration qui mérite d'être examiné.

Qu'est-ce que cela signifie pour vos points de terminaison ?

  • Traitez l'absence de ticket_id dans les appels post-session comme un signal de configuration qui mérite d'être examiné, et non comme un comportement attendu à absorber silencieusement.

  • Si votre configuration ne nécessite pas intentionnellement de recherche de ticket, configurez vos points de terminaison post-session pour gérer correctement un ticket_id manquant. Par exemple, consignez le problème et l'absence d'opération, ou renvoyez un message d'erreur clair et bien structuré au lieu de planter.

Comportement des nouvelles tentatives et des intervalles entre les tentatives

Les nouvelles tentatives se produisent à trois niveaux :

  1. Nouvelle tentative immédiate au niveau HTTP (une deuxième tentative rapide).

  2. Nouvelle tentative au niveau de l'adaptateur (récupération rapide en cas de défaillances du réseau et de réponses temporaires spécifiques).

  3. Nouvelles tentatives au niveau de la commande (nouvelles tentatives de longue traîne sur plusieurs jours).

Nouvelle tentative immédiate au niveau HTTP (nouvelle tentative rapide)

Pour certains états temporaires, la plate-forme effectue jusqu'à deux tentatives au total (une tentative initiale et une nouvelle tentative immédiate). Cela s'applique généralement aux états d'erreur suivants :

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

Nouvelle tentative au niveau de l'adaptateur (récupération rapide du réseau)

Entre l'appel HTTP et la planification au niveau de la commande, une couche de nouvelle tentative intermédiaire dans l'adaptateur CRM (command_runner.js) gère les échecs qui ne produisent aucune réponse HTTP ou qui correspondent à des messages temporaires spécifiques :

  • Remise en file d'attente immédiate : déclenchée par des erreurs au niveau TCP/socket : ECONNRESET, ENOTFOUND, ESOCKETTIMEDOUT, ETIMEDOUT, ECONNREFUSED, EHOSTUNREACH, EPIPE, EAI_AGAIN. Il s'agit de défaillances réseau qui se produisent avant la réception d'une réponse HTTP.

  • Nouvelle tentative différée de 30 secondes : déclenchée lorsque le message d'erreur est "Too Early" (HTTP 425), "Service Unavailable" ou "Unordered Collection".

  • Non renouvelable à ce niveau : tout le reste est renvoyé au calendrier de nouvelles tentatives au niveau de la commande (couche 3).

Pourquoi est-ce important pour les intégrateurs ?

Ces erreurs se produisent lorsque la plate-forme ne peut pas établir ou maintenir une connexion TCP avec votre point de terminaison. Elles indiquent donc souvent un problème au niveau de votre serveur (serveur en panne, refusant les connexions ou interrompant la connexion en cours de requête), et pas seulement au niveau de l'infrastructure interne. En pratique, certaines défaillances du réseau sont résolues beaucoup plus rapidement que le délai de sept jours prévu au niveau de la commande, souvent en quelques secondes.

Nouvelles tentatives au niveau de la commande (environ 7 jours, 14 tentatives)

Si une opération échoue et peut être relancée, la plate-forme peut la relancer jusqu'à 14 fois sur une période d'environ sept jours, selon le calendrier suivant :

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

Ce comportement de nouvelle tentative de longue traîne peut s'appliquer aux éléments suivants :

  • Opérations de compte.

  • Enregistrer les opérations.

  • Opérations post-session.

Échecs non renouvelables

Certains échecs sont traités comme non renouvelables, par exemple :

  • Échecs de configuration ou de validation (par exemple, les points de terminaison requis ne sont pas configurés ou sont mal configurés).

  • Certaines catégories d'erreurs internes détectées par la plate-forme.

Si vous devez vous assurer qu'un échec est traité comme permanent (aucune nouvelle tentative), contactez l'assistance ou votre équipe d'implémentation pour confirmer la bonne façon d'indiquer un échec non renouvelable dans votre configuration spécifique.

Délais avant expiration et défaillances du réseau

La plate-forme gère deux parcours distincts :

  1. Délais avant expiration au niveau de l'application : lorsque le délai avant expiration HTTP configuré est dépassé (la requête a été envoyée, mais aucune réponse n'a été reçue), la plate-forme génère une erreur interne qui peut être relancée au niveau de la commande (couche 3). Cela signifie que la requête suit le calendrier d'intervalle exponentiel entre les tentatives standard (jusqu'à 14 nouvelles tentatives sur environ sept jours).

  2. Erreurs au niveau TCP/socket : lorsque la connexion échoue au niveau du réseau avant la réception d'une réponse HTTP (par exemple, ETIMEDOUT, ESOCKETTIMEDOUT et ECONNREFUSED), la couche d'adaptateur (couche 2) les intercepte et remet immédiatement la commande en file d'attente. La récupération après ces défaillances est généralement beaucoup plus rapide, souvent en quelques secondes plutôt qu'en suivant le calendrier de 7 jours.

Pourquoi cette distinction est-elle importante ?

  • Un délai d'expiration de l'application (votre serveur a accepté la connexion, mais n'a pas répondu à temps) entraîne des nouvelles tentatives plus lentes.

  • Une défaillance au niveau du réseau (votre serveur n'a pas pu être joint du tout) est relancée beaucoup plus rapidement.

  • Dans les deux cas, la requête peut avoir été partiellement traitée. Les points de terminaison doivent donc être idempotents (voir Créer des points de terminaison résilients (idempotence et conseils de conception)).

Matrice des codes d'état et des comportements de délai avant expiration (avec exemples)

Les tableaux et exemples suivants décrivent comment CCAI Platform gère les différents codes d'état HTTP, les délais avant expiration et les défaillances du réseau.

Tableau récapitulatif des résultats

Les lignes liées à l'ID dans le tableau suivant ne s'appliquent qu'aux points de terminaison configurés pour extraire un ID de la réponse, tels que les points de terminaison de recherche ou de création. La plupart des autres points de terminaison n'effectuent pas d'extraction d'ID de réponse.

Résultat Exemples Nouvelle tentative HTTP immédiate ? Nouvelles tentatives de longue traîne (~7 jours) ? Impact en aval
Réussite d'un point de terminaison d'extraction d'ID 2xx + ID attendu présent dans l'emplacement de réponse configuré. Non Non Le traitement en aval se poursuit avec l'ID extrait.
Recherche sans correspondance 2xx, mais aucun enregistrement n'a été trouvé à l'emplacement configuré. Non Non Comportement normal "Introuvable". Lorsque skip_account_creation ou skip_record_creation est activé, le traitement en aval se poursuit intentionnellement avec des ID nuls.
Créer un 2xx récurrent sans ID 2xx à partir d'un point de terminaison de création, mais l'ID du nouvel enregistrement est manquant à l'emplacement configuré. Non Non Les étapes en aval peuvent se poursuivre avec des données manquantes. Traitez-le comme un problème de configuration ou de contrat de réponse.
Réussite d'un point de terminaison n'extrayant pas d'ID 2xx à partir de points de terminaison tels que les actions de note, de mise à jour ou de pièce jointe qui n'extraient pas d'ID. Non Non Le traitement en aval se poursuit conformément à la chaîne de commande et à la configuration de l'instance.
Erreur temporaire 408, 413, 429, 500, 502, 503, 504, 521, 522 et 524. Oui (deux tentatives au total) Souvent oui Les étapes en aval peuvent être retardées pendant les nouvelles tentatives.
Autres erreurs 400, 401, 403, 404 et d'autres 4xx/5xx. Non Souvent oui Les étapes en aval peuvent être retardées pendant les nouvelles tentatives.
Échec de la configuration/validation une mauvaise configuration ou des points de terminaison manquants. N/A Non La chaîne peut s'arrêter ou se terminer partiellement en fonction de la configuration.
Échec au niveau du réseau (TCP/socket) ECONNRESET, ENOTFOUND, ESOCKETTIMEDOUT, ETIMEDOUT, ECONNREFUSED, EHOSTUNREACH, EPIPE et EAI_AGAIN. N/A Non (géré par l'adaptateur de couche 2) L'adaptateur remet immédiatement en file d'attente ; la récupération est généralement rapide (quelques secondes). Les étapes en aval peuvent être brièvement retardées.
Délai avant expiration au niveau de l'application HTTP timeout exceeded (aucune réponse reçue). N/A Souvent oui (couche 3) Les étapes en aval peuvent être retardées pendant les nouvelles tentatives au niveau de la commande.

Exemple concret avec une configuration d'API générique minimale

Une configuration d'API générique de CRM personnalisé de référence avec les trois points de terminaison utilisés par la chaîne : rechercher ou créer un contact, rechercher ou créer une demande, et un commentaire post-session. Utilisez-le comme point de départ et adaptez-le aux spécificités de votre CRM.

Paramètres au niveau de l'instance

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

Formes de réponse

La forme de la réponse de votre CRM est spécifique au client. response_data_location est un chemin d'accès de style lodash qui atteint l'objet pertinent dans le corps de la réponse analysée. Il n'est pas nécessaire d'encapsuler les réponses dans un champ data de premier niveau. Les exemples suivants montrent des formes plates réalistes par défaut.

Par exemple, un CRM qui imbrique des ressources sous data.contact définirait response_data_location: "data.contact" et un corps de réponse de { "contact": { "id": "c_99812" } }. Le reste de la configuration reste inchangé.

Point de terminaison 1 - contact_find_endpoint

Recherche un contact par numéro de téléphone ou adresse e-mail.

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

Réussite : contact trouvé

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

Contact introuvable

404 Not Found

La plate-forme traite 404 comme "introuvable" (et non comme une erreur). Si skip_account_creation est "false", le flux passe à contact_create_endpoint.

Autre format "Non trouvé" : également valide

200 OK
{}

Certains CRM renvoient 200 OK avec des données vides au lieu de 404 lorsqu'aucun enregistrement ne correspond. La plate-forme gère les deux de manière équivalente : les deux déclenchent l'étape suivante (création, si elle est activée).

Échec temporaire

503 Service Unavailable
}

Déclenche une nouvelle tentative HTTP immédiate de niveau 1 (deux tentatives au total). Si l'échec persiste, l'opération passe aux nouvelles tentatives au niveau de la commande de la couche 3.

Point de terminaison 2 - contact_create_endpoint

Crée un contact. Le champ custom_id_location indique à la plate-forme où trouver l'ID du nouveau contact dans la réponse.

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

Création réussie

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

2xx, mais ID manquant à l'emplacement configuré

200 OK
{}

Le point de terminaison a renvoyé 200 OK sans id à l'emplacement configuré. La plate-forme consigne un avertissement et transmet un contact_id nul en aval (aucune exception n'est générée, aucune nouvelle tentative n'est effectuée). Considérez cela comme un problème de configuration : response_data_location et custom_id_location doivent générer de manière fiable un ID pour tout 2xx que votre point de terminaison renvoie à partir de ce chemin d'accès.

Point de terminaison 3 - case_create_endpoint

Crée une demande d'assistance. La valeur contact_id de l'étape précédente est disponible en tant que {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"
}

Création réussie

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

Avec response_data_location: "data", la plate-forme résout le chemin d'accès au corps de la réponse analysée. Il lit ensuite le champ custom_id_location: "id" → ticket_id = "case_77103", qui est transmis à la post-session.

case_comment_endpoint : point de terminaison 4

Ce point de terminaison ajoute un commentaire de résumé de session au ticket une fois l'appel ou le chat terminé. La variable RECORD_ID contient le ticket_id produit à l'étape 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}"
  }
}

Pour les instances d'API génériques avec case_lookup_url configuré, la plate-forme n'envoie pas ce point de terminaison tant que l'étape de création du ticket n'est pas terminée. Par conséquent, l'absence de RECORD_ID ici indique un problème de configuration, et non un état temporaire.

Variante : création de compte désactivée

Cet exemple est très semblable au précédent, qui concernait une configuration d'API générique minimale, sauf qu'ici, votre instance n'autorise pas la création de contacts dans le CRM. La recherche de compte s'exécute, mais pas la création.

Modification des paramètres d'instance

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

Les modifications apportées aux paramètres de l'instance incluent les comportements suivants :

  • L'étape de compte appelle uniquement contact_find_endpoint. Si aucun contact n'est trouvé, il n'appelle pas contact_create_endpoint.

  • L'étape d'enregistrement reçoit un contact_id nul. La plate-forme procède à la création du ticket sans contact_id : {ACCOUNT_ID} est résolu en une valeur vide, et le champ contact_id est entièrement supprimé de votre charge utile case_create_endpoint.

  • Cela signifie que votre point de terminaison de création de billets doit pouvoir créer des billets sans contact_id dans cette configuration. Si votre CRM nécessite un contact associé pour chaque demande, cette configuration est incompatible.

Modèle défensif dans case_create_endpoint

Sans contact_id, votre CRM dispose de moins de contexte sur l'appelant qu'en temps normal. Vous pouvez utiliser l'assistant =DEFAULT_VALUE pour capturer les informations d'identification disponibles dans la requête et les transmettre en tant que signal de remplacement :

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

L'assistant =DEFAULT_VALUE sélectionne la première valeur non vide. Votre CRM reçoit donc une adresse e-mail ou un numéro de téléphone lorsqu'ils sont disponibles, et la chaîne littérale "anonymous" uniquement lorsque ni l'un ni l'autre ne sont disponibles. Cela est utile pour signaler les demandes qui ne sont associées à aucune coordonnée d'identification.

Variante : flux de tickets en lecture seule (pas de création d'enregistrement)

Les opérations du compte s'exécutent normalement, mais la création de tickets est désactivée. L'intégration n'associe les commentaires qu'aux tickets existants trouvés par la recherche.

Modification des paramètres d'instance

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

Les modifications concernent les comportements suivants :

  • L'étape d'enregistrement appelle case_find_endpoint et utilise le ticket renvoyé. Si aucun ticket n'est trouvé, la chaîne s'arrête à l'étape d'enregistrement : case_create_endpoint n'est pas appelé.

  • Les points de terminaison post-session (case_comment_endpoint, case_update_endpoint et autres) ne sont envoyés que lorsqu'un ticket a été recherché avec succès. La protection ready? côté Rails garantit que ces commandes restent en file d'attente (et finissent par expirer) si aucun ticket_id ne se matérialise.

  • Implication pratique : dans cette configuration, vos points de terminaison post-session ne recevront que les sessions associées à un ticket connu. Vous n'avez pas besoin de gérer la branche "missing ticket_id".

La plate-forme expose à la fois SESSION_TYPE et SESSION_ID en tant que variables de modèle. La méthode la plus propre pour appliquer le modèle de clé composite consiste à l'intégrer directement dans chaque corps de requête pertinent. Vos points de terminaison disposent alors de la clé canonique avec laquelle travailler, sans logique supplémentaire de votre part :

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

Pour le même appel, chaque nouvelle tentative de chaque point de terminaison de la chaîne (compte > enregistrement > post-session) produira le même ccai_session_key. Utilisez-le comme ancrage de déduplication dans la logique de création ou d'upsert de votre CRM. Par exemple, un upsert sur (ccai_session_key, endpoint_kind) absorbera les nouvelles tentatives en toute sécurité sans produire d'enregistrements en double.

Créer des points de terminaison résilients (idempotence et conseils de conception)

Étant donné que les requêtes peuvent être répétées (nouvelle tentative immédiate et nouvelles tentatives sur plusieurs jours), vos points de terminaison doivent être idempotents :

  • Utilisez un identifiant d'interaction composite stable comme clé d'idempotence :

    • Combinez le type de session avec l'ID de session, par exemple call-12345 ou chat-12345.

    • Ne vous fiez pas uniquement à call_id ou chat_id. Les ID de voix et de chat peuvent se chevaucher, car chaque séquence peut commencer à 1.

  • Si vous recevez ce qui semble être une demande en double :

    • Examinez la charge utile pour déterminer s'il s'agit réellement d'un doublon. Certains points de terminaison partagés, tels que les points de terminaison de commentaire ou de note, peuvent être utilisés par plusieurs types de commandes.

    • Pour les opérations de création, les requêtes en double ne devraient pas se produire dans des conditions normales de réussite, mais elles peuvent se produire si le CRM a traité la requête, puis a renvoyé une erreur ou a expiré avant que la plate-forme ne reçoive une réponse de réussite.

    • Lorsqu'une demande de création en double est confirmée, renvoyez l'ID de l'enregistrement précédemment créé au lieu d'un autre enregistrement.

  • Gérez explicitement les ID manquants :

    • L'absence de contact_id lors de la création d'un ticket indique généralement une configuration dans laquelle la recherche ou la création de compte est désactivée. Si votre instance nécessite des comptes, examinez-la au lieu de créer silencieusement des tickets sans contacts.

    • L'absence de ticket_id dans les appels post-session n'est pas attendue pour les configurations d'API génériques standards où la recherche de billets est configurée. Vérifiez la configuration de la recherche de tickets et les modèles de charge utile avant de traiter la requête comme une opération sans effet normale.

  • Pour les mises à jour, préférez définir des champs sur des valeurs spécifiques plutôt que d'incrémenter des compteurs, afin que les appels répétés soient sécurisés.

Dépannage et observabilité

Lorsque vous déboguez une intégration CRM personnalisée, gardez à l'esprit les points suivants :

  • Appels répétés au même point de terminaison :

    • Comparez les codes temporels au calendrier des nouvelles tentatives dans Nouvelles tentatives au niveau de la commande (~7 jours, 14 tentatives).

    • Mettez en corrélation les événements à l'aide de l'identifiant de session composite, tel que le type de session + l'ID de session d'appel ou de chat.

    • Les journaux exportés de la plate-forme CCAI peuvent aider à afficher l'ID de session d'appel ou de chat ainsi que les événements d'API pour la traçabilité.

    • Vérifiez si votre point de terminaison renvoie systématiquement une erreur pouvant être relancée (par exemple, 500) au lieu d'un échec de configuration non relançable.

  • Tentatives qui "ne s'arrêtent pas" :

    • Inspectez les réponses d'erreur renvoyées par votre point de terminaison.

    • Si vous avez l'intention de provoquer un échec permanent, contactez l'assistance pour savoir comment indiquer une erreur non renouvelable pour votre configuration.

  • Le point de terminaison n'a jamais été appelé :

    • Vérifiez les points suivants :

      • Les étapes en amont (compte/enregistrement) ont bien été effectuées et ont généré les ID nécessaires.

      • Le point de terminaison est correctement configuré et activé dans les paramètres de votre CRM personnalisé.

    • Un point de terminaison mal configuré ou désactivé, ou un échec plus tôt dans la chaîne, peut empêcher l'exécution de certaines étapes.

  • Corréler les journaux :

    • Enregistrez la requête et la réponse complètes de votre côté, y compris l'ID d'interaction (call_id/chat_id).

    • Utilisez cet ID pour mettre en corrélation vos journaux CRM avec le comportement de la plate-forme au fil du temps (en particulier lors des nouvelles tentatives).