API des codes de disposition

L'API des codes de disposition permet à votre intégration d'effectuer les opérations suivantes :

  • Obtenez des listes de codes de disposition pour une instance, une file d'attente ou une session.

  • Modifiez les codes de disposition ou les notes (ou les deux) d'une session d'appel ou de chat terminée.

Authentification et URL de base

Tous les points de terminaison de ce document utilisent l'authentification par jeton d'API standard à l'aide d'un jeton d'utilisateur d'API (jeton du porteur).

URL de base : https://SUBDOMAIN.REGION_CODE.ccaiplatform.com

Obtenir la liste des codes de disposition

Obtenez les codes de disposition disponibles. Vous pouvez interroger les données au niveau de l'instance, de la file d'attente et de la session.

Par instance

Renvoie l'arborescence complète des codes de disposition pour l'instance, y compris tous les codes de disposition à plusieurs niveaux.

Exemple de requête

La requête suivante permet d'obtenir la liste complète des codes de disposition :

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

Exemple de réponse

L'exemple de réponse suivant affiche la liste complète des codes de traitement :

{
  "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": []
        }
      ]
    }
  ]
}

Par file d'attente

Renvoie les codes de traitement attribués à une file d'attente. Si aucune liste spécifique à la file d'attente n'est configurée, la liste globale (au niveau de l'instance) est renvoyée.

Exemple de requête

La requête suivante permet d'obtenir les codes de disposition pour une file d'attente :

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

Paramètres de requête

Paramètre Type Obligatoire Description
queue_id entier Oui ID de la file d'attente pour laquelle récupérer les codes de disposition.

Par session

Renvoie les codes de disposition disponibles pour un ID de session donné, en fonction de la dernière file d'attente par laquelle la session a été transférée.

Exemple de requête

La requête suivante permet d'obtenir les codes de disposition d'une session :

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

Paramètres de requête

Paramètre Type Obligatoire Description
session_id entier Oui ID de la session.

Mettre à jour le code et les notes de disposition

Envoyez un code de disposition ou des notes (ou les deux) mis à jour pour un appel ou une session de chat précédemment terminés. Un enregistrement de disposition et une note CRM sont alors créés. Il ne modifie pas l'enregistrement CRM d'origine.

Exemple de requête

La requête suivante met à jour le code de disposition ou les notes d'une session :

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

Paramètres de chemin d'accès

Paramètre Type Obligatoire Description
session_id entier Oui ID de session de l'appel ou du chat à modifier.

Exemple de corps de requête

Voici un exemple de corps de requête :

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

Paramètres du corps de la requête

Paramètre Type Obligatoire Description
disposition_code objet Conditionnel Code de disposition mis à jour. Au moins l'un des champs disposition_code ou notes doit être présent.
disposition_code.id entier Oui (si disposition_code est spécifié) ID du code de traitement.
disposition_code.full_path string Oui (si disposition_code est spécifié) Chemin hiérarchique complet du code de disposition, par exemple /Support/Verification/Pending Documents. Utilisé pour la validation par rapport à l'arborescence de disposition de la session.
notes string Non Notes de l'agent mises à jour. Consultez le tableau Comportement des notes.

Comportement des notes

Valeur Comportement
Présenter avec du texte, par exemple : "notes": "Updated notes" Remplace la note existante par le nouveau texte.
Présenter comme une chaîne vide ("notes": "") Efface explicitement la note existante. La note ne figurera plus dans le fichier de métadonnées de la session. L'historique du CRM conserve les enregistrements précédents.
Omitted (field absent from request) Ne modifie pas la note existante.

Disposition "Ne pas appeler"

Pour envoyer une disposition "Ne pas appeler", utilisez disposition_code.id: -1. Cette option n'est acceptée que lorsque la fonctionnalité Ne pas appeler est activée pour l'instance et qu'une disposition "Ne pas appeler" est configurée. Sinon, l'API renvoie 422 Unprocessable Entity avec le message "La disposition "Ne pas appeler" n'est pas activée pour ce locataire."

Attribution des agents

L'API ne comporte pas d'identité d'agent. Le système attribue l'état aux éléments suivants, par ordre de priorité :

  1. Agent qui a initialement envoyé la disposition pour cette session.

  2. Si aucune disposition d'origine n'existe, l'agent participant le plus récent à l'appel ou au chat.

Si aucun des deux n'existe, l'API renvoie 422 Unprocessable Entity.

Validation

La liste suivante décrit les règles de validation :

  • L'appel ou le chat de la session doivent être terminés. Toute tentative de mise à jour de l'état d'une session active renvoie 422 Unprocessable Entity.

  • Les paramètres disposition_code.id et disposition_code.full_path sont validés par rapport à l'arborescence de disposition de la session (en fonction de la file d'attente par laquelle la session a été routée en dernier).

  • Le paramètre d'administrateur allow_disposition_edit est un contrôle réservé à l'interface utilisateur. L'API publique peut toujours mettre à jour les données de disposition, quel que soit ce paramètre.

Exemple de réponse

L'exemple suivant montre une réponse à une requête réussie :

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

Remarque : Le champ name est résolu par le serveur à partir de l'arborescence de disposition en fonction des valeurs id et full_path spécifiées. Elle est renvoyée dans la réponse pour plus de commodité.

Métadonnées de session

Lorsqu'un état est modifié à l'aide de cette API, les actions suivantes sont effectuées :

  • Stockage externe : le fichier de métadonnées de la session est régénéré et écrase le fichier de métadonnées existant.

  • CRM : une note est créée, ce qui permet de conserver la piste d'audit.

Gestion des exceptions

Cette section décrit la gestion des exceptions.

Codes d'état courants

État Condition Exemple de message
400 Bad Request Champs obligatoires manquants (disposition_code et notes absents) ou format non valide. "Au moins un champ disposition_code ou notes doit être présent."
401 Unauthorized Jeton API manquant ou non valide. "Non autorisé"
403 Forbidden L'utilisateur de l'API n'a pas accès à la session ou au locataire spécifiés. "Interdit"
404 Not Found Session introuvable ou inexistante. "Session introuvable."
422 Unprocessable Entity Divers échecs de validation. Consultez le tableau Scénarios d'entité non traitable 422. Consultez le tableau Scénarios d'entité non traitable 422.

Scénarios d'entité non traitables 422

Scénario Message d'erreur
La session d'appel ou de chat est toujours active "La session n'est pas terminée. La disposition ne peut être modifiée que pour les sessions terminées."
ID de code de disposition introuvable dans l'arborescence de la session "Le code de disposition n'est pas valide pour la file d'attente de cette session."
Disposition "Ne pas appeler" envoyée, mais fonctionnalité non activée "La disposition "Ne pas appeler" n'est pas activée pour ce locataire."
Aucun participant agent ne peut être résolu pour l'attribution "Impossible de déterminer l'agent pour l'attribution de la disposition."

Exemple de réponse

L'exemple suivant montre une réponse d'erreur :

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

Flux d'intégration type

Voici un flux d'intégration typique :

  1. Obtenez les codes de disposition pour la file d'attente ou la session concernée :

    • GET /api/v1/disposition_codes?session_id=SESSION_ID

  2. Présentez l'arborescence des dispositions à l'utilisateur ou au système automatisé pour qu'il puisse faire son choix.

  3. Envoyez la disposition mise à jour :

    • POST /api/v1/sessions/SESSION_ID/disposition

    • Incluez le disposition_code sélectionné, avec id et full_path, ainsi que toutes les notes.

  4. Gérez la réponse :

    • Sur 200 OK : la disposition a été mise à jour. Les enregistrements CRM sont mis à jour automatiquement.

    • En cas d'erreur : affichez le message d'erreur et réessayez ou escaladez le problème, le cas échéant.

Comportement du CRM

Lorsqu'une disposition est envoyée à l'aide de cette API, les événements suivants se produisent :

  • Une note CRM est créée dans le CRM associé, tel que Salesforce, ServiceNow, Zendesk, Dynamics ou HubSpot. La note d'origine n'est pas modifiée.

  • Pour le stockage externe, le fichier de métadonnées de session est écrasé avec les données de disposition mises à jour.

Limite

Les engagements d'appel HubSpot incluent une propriété scalaire hs_call_disposition qui est écrasée (et non ajoutée) à chaque mise à jour de l'état. Bien que l'historique complet soit conservé dans les notes HubSpot, la propriété d'engagement ne reflète que le code de disposition le plus récent.