API dei codici di disposizione

L'API dei codici di disposizione consente alla tua integrazione di eseguire le seguenti operazioni:

  • Recuperare gli elenchi dei codici di disposizione per un'istanza, una coda o una sessione.

  • Aggiornare i codici di disposizione o le note (o entrambi) per una sessione di chiamata o chat completata in precedenza.

Autenticazione e URL di base

Tutti gli endpoint in questo documento utilizzano l'autenticazione standard dei token API tramite un token utente API (token di autenticazione).

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

Recuperare l'elenco dei codici di disposizione

Recupera i codici di disposizione disponibili. Puoi eseguire query a livello di istanza, coda e sessione.

Per istanza

Restituisce l'albero completo dei codici di disposizione per l'istanza, inclusi tutti i codici di disposizione a più livelli.

Esempio di richiesta

La seguente richiesta recupera l'elenco completo dei codici di disposizione:

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

Esempio di risposta

La seguente risposta di esempio mostra l'elenco completo dei codici di disposizione:

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

Per coda

Restituisce i codici di disposizione assegnati a una coda. Se non è configurato alcun elenco specifico della coda, viene restituito l'elenco globale (a livello di istanza).

Esempio di richiesta

La seguente richiesta recupera i codici di disposizione per una coda:

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

Parametri di query

Parametro Tipo Obbligatorio Descrizione
queue_id integer Sì L'ID della coda per cui recuperare i codici di disposizione.

Per sessione

Restituisce i codici di disposizione disponibili per un determinato ID sessione, in base all'ultima coda in cui è stata instradata la sessione.

Esempio di richiesta

La seguente richiesta recupera i codici di disposizione per una sessione:

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

Parametri di query

Parametro Tipo Obbligatorio Descrizione
session_id integer Sì L'ID sessione.

Aggiornare il codice di disposizione e le note

Invia un codice di disposizione o delle note aggiornati (o entrambi) per una sessione di chiamata o chat completata in precedenza. Vengono creati un nuovo record di disposizione e una nota CRM. Non viene modificato il record CRM originale.

Esempio di richiesta

La seguente richiesta aggiorna il codice di disposizione o le note per una sessione:

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

Parametri del percorso

Parametro Tipo Obbligatorio Descrizione
session_id integer Sì L'ID sessione della chiamata o della chat da aggiornare.

Esempio di corpo della richiesta

Il seguente esempio mostra un corpo della richiesta:

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

Parametri del corpo della richiesta

Parametro Tipo Obbligatorio Descrizione
disposition_code oggetto Condizionale Il codice di disposizione aggiornato. Deve essere presente almeno uno tra disposition_code e notes.
disposition_code.id integer Sì (se è specificato disposition_code) L'ID del codice di disposizione.
disposition_code.full_path string Sì (se è specificato disposition_code) Il percorso gerarchico completo del codice di disposizione, ad esempio, /Support/Verification/Pending Documents. Utilizzato per la convalida rispetto all'albero di disposizione della sessione.
notes string No Le note dell'agente aggiornate. Consulta la tabella Comportamento delle note.

Comportamento delle note

Valore Comportamento
Presente con il testo, ad esempio, "notes": "Updated notes" Sostituisce la nota esistente con il nuovo testo.
Presente come stringa vuota ("notes": "") Cancella esplicitamente la nota esistente. Il file di metadati della sessione non conterrà più la nota. La cronologia CRM conserva i record precedenti.
Omesso (il campo non è presente nella richiesta) Lascia invariata la nota esistente.

Disposizione "Non chiamare"

Per inviare una disposizione "Non chiamare", utilizza disposition_code.id: -1. Questa opzione è accettata solo se l'istanza ha la funzionalità Non chiamare abilitata e se è configurata una disposizione Non chiamare. In caso contrario, l'API restituisce 422 Unprocessable Entity con il messaggio: "Do Not Call disposition is not enabled for this tenant."

Attribuzione dell'agente

L'API non include l'identità di un agente. Il sistema attribuisce la disposizione a quanto segue, in ordine di priorità:

  1. L'agente che ha inviato originariamente la disposizione per questa sessione.

  2. Se non esiste una disposizione originale, l'agente partecipante più recente alla chiamata o alla chat.

Se non esiste nessuno dei due, l'API restituisce 422 Unprocessable Entity.

Convalida

Il seguente elenco descrive le regole di convalida:

  • La chiamata o la chat della sessione deve essere terminata. Se tenti di aggiornare la disposizione in una sessione attiva, viene restituito 422 Unprocessable Entity.

  • I parametri disposition_code.id e disposition_code.full_path vengono convalidati rispetto all'albero di disposizione della sessione (in base alla coda in cui è stata instradata la sessione per ultima).

  • L'impostazione dell'amministratore allow_disposition_edit è un controllo solo dell'interfaccia utente. L'API pubblica può sempre aggiornare i dati di disposizione indipendentemente da questa impostazione.

Esempio di risposta

Il seguente esempio mostra una risposta a una richiesta riuscita:

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

Nota: il campo name viene risolto dal server dall'albero di disposizione in base ai valori id e full_path specificati. Viene restituito nella risposta per comodità.

Metadati della sessione

Quando una disposizione viene aggiornata utilizzando questa API, si verifica quanto segue:

  • Archiviazione esterna: il file di metadati della sessione viene rigenerato e sovrascrive il file di metadati esistente.

  • CRM: viene creata una nuova nota, mantenendo la traccia di controllo.

Gestione degli errori

Questa sezione descrive la gestione degli errori.

Codici di stato comuni

Stato Condizione Messaggio di esempio
400 Bad Request Campi obbligatori mancanti (disposition_code e notes entrambi assenti) o formato non valido. "At least one of disposition_code or notes must be present."
401 Unauthorized Token API non valido o mancante. "Unauthorized"
403 Forbidden L'utente API non ha accesso alla sessione o al tenant specificati. "Forbidden"
404 Not Found Sessione non trovata o inesistente. "Session not found."
422 Unprocessable Entity Vari errori di convalida. Consulta la tabella Scenari di entità non elaborabile 422. Consulta la tabella Scenari di entità non elaborabile 422.

Scenari di entità non elaborabile 422

Scenario Messaggio di errore
La sessione di chiamata o chat è ancora attiva "Session has not ended. Disposition can only be updated for completed sessions."
ID del codice di disposizione non trovato nell'albero della sessione "Disposition code is invalid for this session's queue."
Disposizione Non chiamare inviata, ma la funzionalità non è abilitata "Do Not Call disposition is not enabled for this tenant."
Impossibile risolvere l'agente partecipante per l'attribuzione "Unable to determine agent for disposition attribution."

Esempio di risposta

Il seguente esempio mostra una risposta di errore:

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

Flusso di integrazione tipico

Di seguito è riportato un flusso di integrazione tipico:

  1. Recupera i codici di disposizione per la coda o la sessione pertinente:

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

  2. Presenta l'albero di disposizione all'utente o al sistema automatizzato per la selezione.

  3. Invia la disposizione aggiornata:

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

    • Includi il codice di disposizione selezionato, con id e full_path, e le eventuali note.

  4. Gestisci la risposta:

    • In caso di risposta 200 OK: la disposizione è stata aggiornata. I record CRM vengono aggiornati automaticamente.

    • In caso di errore: visualizza il messaggio di errore e riprova o esegui l'escalation in base alle esigenze.

Comportamento del CRM

Quando una disposizione viene inviata utilizzando questa API, si verifica quanto segue:

  • Viene creata una nuova nota CRM nel CRM connesso, ad esempio Salesforce, ServiceNow, Zendesk, Dynamics o HubSpot. La nota originale non viene modificata.

  • Per l'archiviazione esterna, il file di metadati della sessione viene sovrascritto con i dati di disposizione aggiornati.

Limitazione

Gli impegni di chiamata di HubSpot includono una proprietà scalare hs_call_disposition che viene sovrascritta (non aggiunta) a ogni aggiornamento della disposizione. Sebbene la cronologia completa venga conservata nelle note di HubSpot, la proprietà dell'impegno riflette solo il codice di disposizione più recente.