Configurare le intestazioni SIP X per gli agenti abilitati per la voce

Questo articolo illustra come configurare le intestazioni X SIP (Session Initiation Protocol) per le chiamate in ingresso e in uscita negli agenti abilitati per la voce di Copilot Studio da usare in Dynamics 365 Contact Center.

I SIP X-header ti permettono di trasferire metadati personalizzati tra i sistemi telefonici e i tuoi agenti abilitati alla voce. Gli agenti con comandi vocali Dynamics 365 Contact Center supportano sia gli X-headers in ingresso che quelli in uscita. Questa configurazione consente uno scambio di dati senza soluzione di continuità durante i trasferimenti delle chiamate e l'instradamento.

Prerequisiti

  • Dynamics 365 Contact Center con agenti abilitati per la voce

  • accesso a Copilot Studio con autorizzazioni appropriate

  • Instradamento diretto per la configurazione della telefonia

  • Conoscenza di base della creazione di argomenti di Copilot Studio e gestione delle variabili

Configura le intestazioni X in ingresso

Gli X-header in ingresso contengono metadati trasmessi da sistemi telefonici esterni al tuo agente abilitato alla voce. Per ricevere e utilizzare questi dati, è necessario configurare un nodo Parse Value per estrarre le informazioni X-header dalla Conversation.SipXHeader variabile di sistema.

Requisiti in arrivo per l'intestazione X

  • Conteggio massimo: cinque intestazioni X per chiamata in arrivo.

  • Requisito di denominazione: Tutti i nomi delle intestazioni X devono iniziare con x-.

    Annotazioni

    In Copilot Studio, tutte le intestazioni X in ingresso devono iniziare con lettere minuscole x-, anche se il sistema esterno che invia l'intestazione X usa un X- maiuscolo. L'intestazione X in uscita definita in Copilot Studio può essere in lettere minuscole o maiuscole, a seconda di come lo prevede il sistema esterno.

  • Lunghezza del nome: fino a 64 caratteri.

  • Lunghezza del valore: fino a 256 caratteri.

  • Uno schema JSON è richiesto per tutti gli X-header attesi.

  • Aggiorna lo schema JSON quando cambiano i nomi degli X-header.

  • Dipendenza dai dati del canale: le intestazioni X devono essere presenti in Conversation.SipXHeader.

Aggiungi Gestione Variabile - Nodo Parse Value

  1. Passare all'argomento del tuo agente abilitato con comandi vocali.

  2. Aggiungi un nuovo nodo di argomento.

  3. Seleziona Gestione variabili e seleziona Valore di analisi.

    Screenshot dell'opzione di gestione delle variabili, evidenziando Parse value.

Configura il nodo Parse Value

  1. Dal menu Sistema , imposta il campo dei valori di analisi su Conversation.SipXHeader.

  2. Imposta il tipo di dato su Da campione.

  3. Definisci la struttura attesa degli X-header selezionando Get schema from sample JSON.

    Screenshot del nodo dei valori di analisi, che mostra i valori di configurazione.

Definisci lo schema JSON per le intestazioni X

Nella finestra di dialogo Ottieni schema dal JSON di esempio, fornisci la struttura JSON che include i nomi degli X-header che ti aspetti di ricevere. Ad esempio, se ti aspetti header come X-CallID e X-AAI-Incoming in una chiamata in entrata, aggiungile al tuo schema JSON.

Screenshot di un esempio di finestra di dialogo per uno schema JSON.

Seleziona Conferma per applicare lo schema.

Importante

La piattaforma "Dynamics 365 Contact Center" normalizza sempre i nomi delle intestazioni X per usare un prefisso in minuscolo x-, indipendentemente dal modo in cui il sistema esterno li invia. Ciò significa:

  • Se il sistema esterno invia X-CallID, devi definirlo come x-CallID nel tuo schema.

  • Se il sistema esterno invia X-AAI-Incoming, devi definirlo come x-AAI-Incoming nel tuo schema.

Anche se il sistema esterno può usare la maiuscolo X-, il tuo schema deve sempre usare la minuscola x- affinché la piattaforma possa mappare e processare correttamente le intestazioni.

Esempio JSON per le X-header

{

"x-CallID": "",

"x-AAI-Incoming": ""  
}

Salva i dati analizzati

  1. Crea o seleziona una variabile nel campo Save as (ad esempio, IncomingSipXHeader).

    Screenshot della configurazione delle proprietà variabili da utilizzare con un X-header SIP.

  2. Imposta l'ambito della variabile su Globale per permettere l'accesso su più argomenti nel tuo agente.

Accedi ai valori delle X-header nei tuoi argomenti

Una volta configurato, puoi accedere ai singoli valori delle intestazioni X usando la notazione dei punti, simile ai seguenti esempi:

  • Global.IncomingSipXHeader.'x-AAI-Incoming'

  • IncomingSIPXHeaders.sipXHeader.'X-CallID'

Comportamento di runtime

  • Copilot Studio riceve solo le prime cinque intestazioni X inviate dal sistema esterno.

  • Copilot Studio popola automaticamente il record con i valori degli header X quando i nomi coincidono con lo schema.

  • I titoli X mancanti hanno valori di stringa vuoti.

  • Gli aggiornamenti dello schema sono necessari quando i nomi delle intestazioni X cambiano o se si desiderano ricevere intestazioni aggiuntive.

Configura le intestazioni X in uscita

Puoi trasferire dati personalizzati quando inoltri chiamate a numeri di telefono esterni, utilizzando le intestazioni X in uscita. Configura queste intestazioni nel nodo Transfer conversation.

Requisiti in uscita per l'intestazione X

  • Conteggio massimo: cinque intestazioni X per trasferimento.

  • Requisito di denominazione: Tutti i nomi delle intestazioni X possono iniziare con X- o x-, a seconda di ciò che il sistema esterno si aspetta.

    Annotazioni

    In Copilot Studio, tutte le intestazioni X in ingresso devono iniziare con lettere minuscole x-, anche se il sistema esterno che invia l'intestazione X usa un X- maiuscolo. L'intestazione X in uscita definita in Copilot Studio può essere in lettere minuscole o maiuscole, a seconda di come lo prevede il sistema esterno.

  • Lunghezza del nome: fino a 64 caratteri.

  • Lunghezza del valore: fino a 256 caratteri.

  • Tipo di trasferimento: disponibile solo per il trasferimento di numeri di telefono esterni.

Configura il nodo di conversazione Transfer

  1. Aggiungi un nodo Trasferisci la conversazione al flusso dell'argomento.

  2. In Tipo di trasferimento, seleziona Trasferimento numero di telefono esterno e inserisci il numero di trasferimento. Per esempio, +18005551212.

Configura le X-header nelle proprietà del nodo di conversazione di trasferimento

  1. Seleziona l'icona Altro (…) del nodo, quindi seleziona Proprietà.

  2. Seleziona + Aggiungi per aggiungere coppie di chiavi e valori per l'X-header.

    Screenshot di un nodo di conversazione Transfer.

  3. Definisci le voci dell'intestazione X. I nomi degli X-header in uscita vengono inviati esattamente come li definisci nel nodo di conversazione trasferimento. Scegli il caso appropriato in base a ciò che il sistema ricevente si aspetta.

    • Nome Chiave: Deve iniziare con X- o x- (ad esempio, X-AAI-Outgoing o X-CallID)
    • Valore: inserisci un valore statico o assegna una variabile

    Screenshot delle proprietà della conversazione di trasferimento.

Procedure consigliate

Seguire queste linee guida per la progettazione degli schemi, la gestione delle variabili, la gestione degli errori, e delle prestazioni quando si lavora con gli X-header SIP nei tuoi agenti abilitati per la voce.

Progettazione dello schema

  • Usa nomi descritivi di X-header che indichino chiaramente il loro scopo.

  • Mantieni aggiornato lo schema JSON quando cambiano i requisiti degli X-header.

  • Documenta lo schema del tuo X-header per riferimento del team e per la risoluzione dei problemi.

Gestione delle variabili

  • Usa variabili globali per i dati X-header che devono essere consultati tra i vari argomenti.

  • Scegli nomi di variabili significative (ad esempio, IncomingSIPXHeaders o CustomerXHeaders).

  • Inizializza le variabili fin dall'inizio del tuo flusso di conversazione.

Gestione degli errori

  • Controlla sempre la presenza degli X-header prima di usare valori nella tua logica.

  • Implementare un comportamento di fallback per dati X-header mancanti o non validi.

  • Fai un test approfondito con vari scenari di X-header.

Considerazioni sulle prestazioni

  • Analizza le intestazioni X all'inizio del flusso di conversazione.

  • Cache usa spesso valori in variabili separate se necessario.

  • Evita l'analisi ripetuta degli stessi dati del canale.

Problemi comuni con le intestazioni X in entrata

Se le intestazioni X in ingresso non funzionano come previsto, esaminare questi problemi comuni e i passaggi per la risoluzione dei problemi.

Valori X-header non ricevuti

  • Verifica che lo schema JSON corrisponda esattamente ai nomi attesi degli X-header.

  • Controlla che il nodo Parse Value sia configurato con Conversation.SipXHeader.

  • Assicurati che la variabile sia impostata a portata globale se viene accessibile da più argomenti.

  • Assicurati che non siano previsti più di cinque intestazioni X e che le intestazioni X siano le prime cinque intestazioni X inviati dal sistema esterno.

X-header con valori vuoti o nulli

  • Conferma che il sistema esterno sta inviando X-header con i nomi attesi.

  • Verifica che lo schema JSON includa tutti i nomi delle intestazioni X richiesti con un prefisso minuscolo x-.

Problemi comuni con le intestazioni X in uscita

Se le intestazioni X in uscita non funzionano come previsto, esamina questi problemi comuni e i passaggi per la risoluzione dei problemi.

X-header non inviati durante il trasferimento

  • Verifica che tutti i nomi delle intestazioni X inizino con X- o x-.

  • Assicurati che il tipo di trasferimento sia impostato su Trasferimento di numero di telefono esterno.

  • Assicurati che i valori delle X-header siano assegnati correttamente prima del nodo Trasferimento di conversazione.

Il trasferimento fallisce con le intestazioni X

  • Conferma che i nomi e i valori degli X-header non superino i limiti di lunghezza.

  • Verifica che il sistema ricevente sia in grado di gestire gli X-header inviati.

  • Controlla se ci sono caratteri speciali che potrebbero causare problemi di parsing.

Gestione dello schema

Mantieni lo schema dell'intestazione X organizzato e al corrente man mano che cambiano i requisiti.

Aggiornamento dello schema X-header

  • Per ricevere nuovi X-header, aggiornare il campione JSON in Define JSON schema per X-header.

  • Conferma e salva lo schema aggiornato.

  • Testa lo schema con la nuova configurazione X-header.

  • Last updated on