Concetti e risoluzione dei problemi

Questa pagina descrive le configurazioni specifiche richieste per l'integrazione e la risoluzione dei problemi comuni.

Requisiti di rete di telefonia

Se la tua rete filtra il traffico in uscita, deve consentire il traffico in uscita per la segnalazione SIP e lo streaming multimediale.

Per la segnalazione SIP, deve essere consentito l'intero intervallo IP 74.125.88.128/25 (TCP) sulla porta 5672. Per un insieme di regole firewall più restrittivo, puoi limitare la segnalazione SIP a uno o più server SIP GTP regionalizzati:

• Regione Stati Uniti: us.telephony.goog (74.125.88.132)
• Regione UE: eu.telephony.goog (74.125.88.133)
• Regione APAC: ap.telephony.goog (74.125.88.134)
• Regione Sud America: sa.telephony.goog (74.125.88.135)

Per i media RTP, devi configurare le regole firewall per consentire il traffico destinato all'intervallo IP CIDR 74.125.39.0/24. In genere, le porte richieste per i media sono solo 16384-32767 (TCP+UDP), ma questo intervallo di porte potrebbe essere ampliato in futuro.

Fornitori o modelli di SBC supportati

La tabella seguente elenca i fornitori o i modelli di SBC e le versioni del firmware supportati. Le istruzioni di integrazione dettagliate per ogni fornitore sono collegate alla versione del firmware.

Fornitori e modelli	Versioni del firmware
AudioCodes VE SBC	v7.60A.100.022 (SIPREC, SIP)
Avaya Session Border Controller for Enterprise	v10.2.1.1-104-25336 (SIPREC, SIP)
Oracle E-SBC Acme Packet 4600	SCZ9.3.0 GA (Build 46) (SIPREC, SIP)
Ribbon Swe Core SBC	v12.01.07R000 (SIPREC, SIP)
Cisco Unified Border Element (CUBE)	v17.15.4 (SIPREC, SIP)

Nota: questa tabella rappresenta le versioni del firmware minime supportate che sono state certificate per il funzionamento con l'integrazione SIP. Sono certificate anche le versioni del firmware più recenti che fanno parte della stessa serie principale di patch del firmware.

Protocolli di segnalazione e media SBC supportati

Protocollo di segnalazione	SIP su TLS
Media	SRTP
Crittografia per contenuti multimediali	SDES
Suite di crittografia per contenuti multimediali supportata	AES_CM_128_HMAC_SHA1_80, AEAD_AES_256_GCM
Codec multimediali supportati	G.711 µ-law (PCMU), G.711 A-law (PCMA), Opus

Intestazioni SIP

Quando hai configurato un profilo di conversazione e un numero di telefono, hai creato un profilo di conversazione CCAI con il sipConfig.createConversationOnTheFly impostato su true. L'ID conversazione deve essere generato dinamicamente durante il SIP INVITE utilizzando il valore dell'intestazione SIP di Call-Info o UUI.

Il valore dell'intestazione SIP punta all'endpoint Dialogflow definendo l' Google Cloud ID progetto e l'ID conversazione:

1. L' Google Cloud ID progetto è il progetto che hai utilizzato quando hai configurato un Google Cloud progetto.
2. L'ID conversazione deve essere generato dinamicamente dall'SBC. L'ID conversazione deve essere conforme alla formula dell'espressione regolare [a-zA-Z][a-zA-Z0-9_-]* con la lunghezza dei caratteri nell'intervallo [3,64]. Per generare dinamicamente l'ID conversazione, un pattern comune consiste nell'utilizzare il valore Call-ID nel SIP INVITE e anteporre le lettere per renderlo conforme all'espressione regolare come specificato in precedenza. Ad esempio, se il valore Call-ID è 297363723_79131759_799783510, anteponendo il valore Call-ID con "CID-" lo renderà conforme all'espressione regolare [a-zA-Z][a-zA-Z0-9_-]*.

Intestazione SIP Call-Info

Inserisci un'intestazione SIP personalizzata denominata Call-Info nel SIP INVITE per impostare in modo univoco l'ID conversazione:

Call-Info: <http://dialogflow.googleapis.com/v2beta1/projects/$PROJECT_ID/conversations/$CONVERSATION_ID>;purpose=Goog-ContactCenter-Conversation

Esempio:

Call-Info: <http://dialogflow.googleapis.com/v2beta1/projects/gcp-project-id-12345/conversations/CID-297363723_79131759_799783510>;purpose=Goog-ContactCenter-Conversation

Intestazione SIP UUI

Se l'impostazione dell'intestazione SIP personalizzata Call-Info non è supportata, puoi configurare l'intestazione SIP UUI (User-to-User) nel SIP INVITE per passare l'ID conversazione.

Utilizza gli stessi dati richiesti in Call-Info con l'URL codificato in esadecimale e lo scopo impostato su Goog-ContactCenter-Conversation. Di seguito è riportato un esempio di intestazione, in cui la stringa esadecimale, una volta decodificata, è http://dialogflow.googleapis.com/v2beta1/projects/gcp-project-id-12345/conversations/CID-297363723_79131759_799783510:

User-to-User: 687474703a2f2f6469616c6f67666c6f772e676f6f676c65617069732e636f6d2f763262657461312f70726f6a656374732f6763702d70726f6a6563742d69642d31323334352f636f6e766572736174696f6e732f4349442d3239373336333732335f37393133313735395f373939373833353130;encoding=hex;purpose=Goog-ContactCenter-Conversation

Se è necessario passare dati aggiuntivi all'agente e impostarli come parametro di sessione, puoi farlo passando un elenco di coppie chiave-valore separate da punto e virgola codificate in esadecimale, seguite da ;encoding=hex;purpose=Goog-Session-Param. Verrà creato un parametro di sessione con il nome uui-headers contenente un elenco di stringhe di payload decodificate.

Ad esempio, se è necessario passare la stringa key1=value1;key2=value2, verrà inviata la seguente intestazione UUI, in cui il payload è il valore codificato in esadecimale di key1=value1;key2=value2.

User-to-User: 6B6579313D76616C7565313B6B6579323D76616C756532;encoding=hex;purpose=Goog-Session-Param

che comporterebbe la creazione del seguente parametro di sessione.

{
    "uui-headers": ["key1=value1;key2=value2"]
}

Se l'SBC supporta l'invio di più intestazioni UUI, puoi inviare singole stringhe chiave-valore per ogni intestazione UUI e queste saranno disponibili come valori singoli nel parametro di sessione uui-headers.

Il seguente snippet prende il valore parametro e poi lo suddivide più volte per accedere al valore appropriato per la variabile key2 nella stringa.

$sys.func.GET($sys.func.SPLIT($sys.func.GET($sys.func.SPLIT($session.params.uui-headers,";"),1),"="),1)

L'esempio seguente mostra una funzione chiamata da un attivatore nei blocchi di codice del playbook, ad es. @PlaybookStartHandler, che viene chiamato all'inserimento del playbook. Altre funzioni chiamano questa funzione per ottenere i valori dal parametro uui-headers.

def _get_fromuui(attribute):
    try:
        uui_headers_src = history.playbook_input.action_parameters['uui-headers']
        # If uui_headers_src is a string, split by ';'
        if isinstance(uui_headers_src, str):
            headers = uui_headers_src.split(';')
        else:
            # If it's a list, join and split
            headers = ';'.join(uui_headers_src).split(';')
        for header in headers:
            header = header.strip()
            if header.lower().startswith(f"{attribute.lower()}="):
                return header[len(attribute) + 1:]
        return ""
    except Exception:
        return ""

È possibile inviare dati aggiuntivi utilizzando intestazioni UUI separate con valori "purpose" diversi. Questi valori vengono aggiunti all' Conversation.telephonyConnectionInfo oggetto. Tieni presente che questi dati non sono disponibili per l'agente Dialogflow CX in fase di runtime.

Intestazioni SIP x

Le intestazioni SIP che iniziano con x- possono essere passate all'agente e impostate come parametro di sessione. Le intestazioni SIP sono disponibili nel parametro di sessione x-headers. Il prefisso x- viene rimosso dal nome dell'intestazione nel parametro di sessione.

Ad esempio, se il SIP INVITE contiene la seguente intestazione:

x-billing-id: 12345

Il parametro di sessione x-headers conterrà:

{
    "x-headers": {
        "billing-id": "12345"
    }
}

Per accedere al valore:

$session.params.x-headers.billing-id

Passare le informazioni dell'agente umano

Se devi passare informazioni specifiche per gli agenti umani, puoi impostare l'attributo dell'etichetta media del protocollo SDP (Session Description Protocol) per il flusso RTP (Real-time Transport Protocol) dell'agente umano sul valore dei dati richiesto. Esempio: none a=label:7382373482 Questi dati verranno inseriti nel sip_recording_media_label campo e saranno disponibili nell'New message notification argomento Pub/Sub contenente le trascrizioni. Cerca il sip_recording_media_label campo nel messaggio Pub/Sub Message.attributes.

Avviso: per motivi di conformità, non passare dati utente PII nelle intestazioni SIP. Devono essere utilizzate solo per passare coppie chiave-valore non PII.

Configurare i ruoli dei partecipanti e l'ordine dei flussi multimediali

Per impostazione predefinita, il primo flusso multimediale è associato al ruolo del partecipante END_USER e i flussi multimediali successivi sono associati al ruolo del partecipante HUMAN_AGENT.

Se hai bisogno di un comportamento diverso (ad esempio, in un sistema di chiamata in uscita), l'URL passato nell'intestazione deve avere il parametro roles aggiunto.

Esempio: none http://dialogflow.googleapis.com/v2beta1/projects/gcp-project-id-12345/conversations/CID-297363723_79131759_799783510?roles=HUMAN_AGENT,END_USER

L'URL specifica che il primo flusso multimediale deve avere il ruolo HUMAN_AGENT e il secondo flusso multimediale deve avere il ruolo END_USER. Puoi applicare il parametro roles con l' Call-Info o UUI intestazione SIP.

Impostare parametri aggiuntivi per una determinata conversazione

Per impostare parametri aggiuntivi per una determinata conversazione, utilizza la MatchIntentRequest chiamata RPC. Puoi impostare query_params.parameters sulle coppie chiave-valore richieste e query_input.text su un valore simile a "Setting parameters".

Effettua la chiamata API dopo la risposta 200 OK per il SIP INVITE iniziale, a questo punto la conversazione è stata creata. L'ID sessione per MatchIntentRequest è lo stesso ID conversazione fornito nell'intestazione Call-Info nell'INVITE.

Utilizzare SIP REFER per trasferire una chiamata a un endpoint SIP

Per trasferire una chiamata da un agente virtuale a un endpoint SIP, utilizza il metodo SIP REFER. Includi un payload nel campo Live agent handoff e imposta il campo Telephony transfer call sul numero impostato nel campo Refer-To SIP REFER in uscita. Il payload Live agent handoff dovrebbe essere simile al seguente esempio di codice.

{
    "sip-refer": true
}

Se i dati devono essere passati da Dialogflow CX, è possibile utilizzare le intestazioni UUI e le intestazioni x per passare stringhe di dati. Se vuoi eseguire un SIP REFER e passare 2 coppie chiave-valore in un'intestazione UUI e 2 intestazioni x, puoi utilizzare un payload Live agent handoff simile al seguente esempio di codice.

{
    "sip-refer": true,
    "uui-headers": [
        "key1=value1;key2=value2"
    ],
    "x-headers": {
        "header1": "value1",
        "header2": "value2"
    }
}

Verrà generato un SIP REFER con le seguenti intestazioni UUI e x.

User-to-User: <hex encoded "key1=value1;key2=value2">;encoding=hex;purpose=Goog-Session-Param
x-header1: value1
x-header2: value2

Utilizzare SIP INVITE per conferire una chiamata con un altro endpoint SIP

Per conferire una chiamata da un cliente finale a un agente umano accessibile tramite un endpoint SIP, utilizza il metodo SIP INVITE. In questo modo, Google rimane nel percorso multimediale e consente l'utilizzo delle funzionalità di Agent Assist. Imposta il campo Telephony transfer call sul numero impostato nel campo To SIP INVITE in uscita.

Se i dati devono essere passati da Dialogflow CX, è possibile utilizzare le intestazioni UUI e le intestazioni x per passare stringhe di dati. Se vuoi eseguire un SIP INVITE e passare 2 coppie chiave-valore in un'intestazione UUI e 2 intestazioni x, puoi utilizzare un payload Live agent handoff simile al seguente esempio di codice.

{
    "uui-headers": [
        "key1=value1;key2=value2"
    ],
    "x-headers": {
        "header1": "value1",
        "header2": "value2"
    }
}

Verrà generato un SIP INVITE con le seguenti intestazioni UUI e x.

User-to-User: <hex encoded "key1=value1;key2=value2">;encoding=hex;purpose=Goog-Session-Param
x-header1: value1
x-header2: value2

Passare i dati in un SIP BYE

Se vai a End Session, viene attivato un SIP BYE. Se vuoi passare i dati da Dialogflow CX, puoi utilizzare le intestazioni UUI o le intestazioni x per passare stringhe di dati. Prima di passare a End Session, devi instradare la chiamata a una pagina che definisce il payload Live agent handoff simile al seguente esempio di codice.

{
    "uui-headers": [
        "key1=value1;key2=value2"
    ],
    "x-headers": {
        "header1": "value1",
        "header2": "value2"
    }
}

Verrà generato un SIP BYE con le seguenti intestazioni UUI e x.

User-to-User: <hex encoded "key1=value1;key2=value2">;encoding=hex;purpose=Goog-Session-Param
x-header1: value1
x-header2: value2

Attivare un'azione quando il chiamante remoto riaggancia

La nuova API BiDi (use_bidi_streaming=True in ConversationProfile) supporta l'attivazione di una chiamata di strumenti all'interno di un playbook o di una chiamata webhook all'interno di un flusso quando il chiamante remoto riaggancia.

Quando il chiamante remoto riaggancia e Dialogflow CX riceve un messaggio SIP BYE, viene attivato l'evento personalizzato sys.remote-call-disconnected. Se crei un gestore con questo nome evento specifico, puoi utilizzarlo per attivare una chiamata di strumenti con un playbook o una chiamata webhook all'interno di un flusso.

Consentire solo le chiamate da SBC

Per rifiutare le chiamate dalla PSTN e connettere solo le chiamate provenienti dal tuo SBC, aggiorna l' PhoneNumber oggetto per specificare il allowedSipTrunks messaggio. Se l'integrazione utilizza un trunk SIP, puoi specificare un elenco di ID trunk SIP specifici. Se il messaggio viene creato con un elenco vuoto, è consentito qualsiasi trunk SIP. Se viene stabilita un'interconnessione privata, fornisci l'ID operatore fornito dal team di telefonia di Google.

Risoluzione dei problemi

Il team di Google potrebbe chiederti di fornire i seguenti artefatti per facilitare la risoluzione dei problemi del ping SIP OPTIONS e delle chiamate di test effettuate:

1. Acquisizione del pacchetto di rete
2. Traccia di debug SIP che mostra l'intestazione completa e il SDP SIP:
   • Valore Call-ID
   • Valore Call-Info (se presente)

Acquisizione del pacchetto di rete

L'acquisizione del pacchetto di rete dovrebbe mostrare quanto segue:

1. Un handshake TCP completo a 3 vie (SYN, SYN-ACK, ACK) tra l'SBC e i server SIP GTP comunicati tramite la porta TCP 5672. Se non è stato possibile stabilire la connessione TCP, i possibili problemi sono:

   • La rete blocca il traffico in uscita.
   • La comunicazione non viene inviata a uno dei server SIP GTP regionalizzati. Vedi il requisito di rete per la connettività di telefonia.
   • La comunicazione non viene inviata tramite la porta TCP 5672.

2. Un handshake di connessione TLS completo con quanto segue:

   • TLS v1.2 o versioni successive avviate dall'SBC.
   • L'SBC che avvia un "Client Hello" e GTP che risponde con "Server Hello".
   • Processo di autenticazione TLS reciproca.
     • GTP risponde con il proprio certificato TLS del server autenticato dall'SBC.
     • L'SBC invia il proprio certificato TLS client autenticato da GTP.
   • Canale crittografato stabilito come evidenziato da "Encrypted Handshake Message".
   • Prova che i "Dati applicazioni" vengono trasmessi tramite il canale TLS.

   Se non è stato possibile stabilire la connessione TLS, i possibili problemi sono:

   • Il trunk SIP non è stato creato sul lato GTP.
   • Il nome di dominio completo (FQDN) configurato del trunk SIP non corrisponde al nome di dominio completo (FQDN) presentato nel certificato TLS (attributo CN o SAN) dell'SBC.
   • Versione TLS non supportata, sono supportate solo la versione TLS 1.2 o versioni successive.
   • La suite di crittografia richiesta non è supportata, vedi la configurazione TLS dell'SBC.
   • Fornitori di certificati TLS non attendibili, vedi la configurazione TLS dell'SBC.

3. La traccia di debug SIP dovrebbe mostrare quanto segue:

   • Intestazione SIP Call-Info del cliente inserita in questo formato: none Call-Info: <http://dialogflow.googleapis.com/v2beta1/projects/$PROJECT_ID/conversations/$CONVERSATION_ID>;purpose=Goog-ContactCenter-Conversation

     Esempio: none Call-Info: <http://dialogflow.googleapis.com/v2beta1/projects/gcp-project-id-12345/conversations/CID-297363723_79131759_799783510>;purpose=Goog-ContactCenter-Conversation

   • Le intestazioni SIP mostrano il numero di telefono in formato E.164 ([phone]).

   • Le intestazioni SIP mostrano gli indirizzi IP pubblici utilizzati nell'URI della richiesta e in altri campi dell'intestazione SIP (ad esempio To, From, Via). Gli indirizzi IP privati verranno rifiutati.

   • Le informazioni di connessione SDP SIP (c= ... ) sono specificate con un indirizzo IP pubblico. Gli indirizzi IP privati verranno rifiutati.

   • Assicurati che la prioritizzazione dei media invii prima il flusso degli utenti finali e poi il flusso multimediale dell'agente umano, perché per impostazione predefinita GTP considera il primo flusso multimediale come quello degli utenti finali.

   Se ricevi un codice di risposta di errore SIP:

   • Il codice di risposta di errore SIP 400 (ad esempio, 488 Not Acceptable Here) indica probabilmente che GTP ha rifiutato un'intestazione SIP o una configurazione SDP multimediale SIP.
   • Un codice di risposta di errore SIP 600 (errore SIP 603 Declined) indica probabilmente un problema relativo alla quota. Per informazioni dettagliate su come richiedere un aumento, consulta la pagina Quote e limiti.