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ù restrittive, 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 contenuti multimediali 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 contenuti multimediali sono solo 16384-32767 (TCP+UDP), ma questo intervallo di porte potrebbe essere ampliato in futuro.

Fornitori o modelli SBC supportati

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

Fornitori e modelli	Versioni 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	v11.01.01R005
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 multimediali SBC supportati

Protocollo di segnalazione	SIP su TLS
Media	SRTP
Crittografia per contenuti multimediali	SDES
Suite di crittografia multimediale 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 sipConfig.createConversationOnTheFly impostato su true. L'ID conversazione deve essere generato dinamicamente durante l'INVITO SIP utilizzando il valore dell'intestazione SIP di Call-Info o UUI.

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

1. L'ID progetto Google Cloud è il progetto che hai utilizzato quando hai configurato un progetto Google Cloud .
2. L'ID conversazione deve essere generato dinamicamente dal SBC. L'ID conversazione deve essere conforme alla formula dell'espressione regolare [a-zA-Z][a-zA-Z0-9_-]* con la lunghezza dei caratteri compresa nell'intervallo [3,64]. Per generare dinamicamente l'ID conversazione, un pattern comune è utilizzare il valore Call-ID nell'INVITE SIP e anteporre delle lettere per renderlo conforme all'espressione regolare specificata in precedenza. Ad esempio, se il valore dell'ID chiamata è 297363723_79131759_799783510, l'aggiunta del prefisso "CID-" al valore dell'ID chiamata lo renderebbe conforme all'espressione regolare [a-zA-Z][a-zA-Z0-9_-]*.

Intestazione SIP Call-Info

Inserisci un'intestazione SIP personalizzata chiamata Call-Info nell'INVITO SIP 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) nell'invito SIP per trasmettere 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 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 separato da punto e virgola di coppie chiave-valore codificate in esadecimale, seguito 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 trasmettere la stringa key1=value1;key2=value2, verrà inviata la seguente intestazione UUI, dove 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 sessione.

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

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

Lo snippet seguente prende il valore del parametro e 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)

Il seguente esempio mostra una funzione chiamata da un trigger nei blocchi di codice del playbook, ad esempio: @PlaybookStartHandler, che viene chiamato all'ingresso nel playbook. Altre funzioni chiamano questa funzione per ottenere 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'oggetto Conversation.telephonyConnectionInfo. Tieni presente che questi dati non sono disponibili per l'agente Dialogflow CX in fase di runtime.

Intestazioni X SIP

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

Ad esempio, se l'INVITE SIP contiene la seguente intestazione:

x-billing-id: 12345

Il parametro sessione x-headers conterrà:

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

Per accedere al valore:

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

Trasmettere le informazioni dell'agente umano

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

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

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

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

Se hai bisogno di un comportamento diverso (ad esempio, in un sistema di chiamate in uscita), l'URL passato nell'intestazione deve avere il parametro dei ruoli 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 stream multimediale deve avere il ruolo HUMAN_AGENT e il secondo stream multimediale deve avere il ruolo END_USER. Puoi applicare il parametro roles con l'intestazione Call-Info o UUI SIP.

Impostare parametri aggiuntivi per una determinata conversazione

Per impostare parametri aggiuntivi in una determinata conversazione, utilizza la chiamata RPC MatchIntentRequest. Puoi impostare query_params.parameters sulle coppie chiave-valore richieste e query_input.text su un valore come "Impostazione dei parametri".

Effettua la chiamata API dopo la risposta 200 OK per l'INVITO SIP iniziale, a quel 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 SIP REFER Refer-To in uscita. Il payload Live agent handoff dovrebbe essere simile al seguente esempio di codice.

{
    "sip-refer": true
}

Se i dati devono essere trasferiti al di fuori di Dialogflow CX, è possibile utilizzare le intestazioni UUI e x-header per trasferire stringhe di dati. Se vuoi eseguire un'operazione SIP REFER e distribuire due coppie chiave-valore in un'intestazione UUI e due 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"
    }
}

In questo modo verrà generato un SIP REFER con i seguenti UUI e x-header.

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 organizzare una conferenza con un altro endpoint SIP

Per trasferire 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 SIP INVITE To in uscita.

Se i dati devono essere trasferiti al di fuori di Dialogflow CX, è possibile utilizzare le intestazioni UUI e x-header per trasferire stringhe di dati. Se vuoi eseguire un'operazione SIP INVITE e distribuire due coppie chiave-valore in un'intestazione UUI e due 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 INVITE SIP con i seguenti UUI e x-header.

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

Trasferire i dati in un SIP BYE

Se vai a End Session, viene attivato un SIP BYE. Se vuoi trasmettere dati al di fuori di Dialogflow CX, puoi utilizzare le intestazioni UUI o x-headers per trasmettere stringhe di dati. Instradare la chiamata a una pagina che ha definito il payload Live agent handoff in modo simile al seguente esempio di codice prima di passare a End Session.

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

Verrà generato un SIP BYE con i seguenti UUI e x-header.

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 allo strumento 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 strumento con un playbook o una chiamata webhook all'interno di un flusso.

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 l'SDP SIP:
   • Valore dell'ID chiamata
   • Valore Call-Info (se esistente)

Acquisizione del pacchetto di rete

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

1. Un handshake TCP a tre vie completo (SYN, SYN-ACK, ACK) tra il tuo 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 tua rete sta bloccando il traffico in uscita.
   • La comunicazione non viene inviata a uno dei server SIP GTP regionalizzati. Consulta Requisito di rete per la connettività di telefonia.
   • La comunicazione non viene inviata tramite la porta TCP 5672.

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

   • TLS v1.2 o versioni successive avviate dal tuo SBC.
   • Il tuo 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, che viene autenticato dal tuo SBC.
     • L'SBC invia il proprio certificato TLS client, autenticato da GTP.
   • Il canale criptato è stato stabilito come dimostrato dal "Messaggio di handshake criptato".
   • Prova della trasmissione dei "dati delle applicazioni" sul 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 nell'attributo CN o SAN del certificato TLS dell'SBC.
   • La versione di TLS non è supportata. Sono supportate solo TLS versione 1.2 o versioni successive.
   • La suite di crittografia richiesta non è supportata, vedi Configurazione TLS di SBC.
   • Fornitori di certificati TLS non attendibili, vedi Configurazione TLS di 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 nel formato E.164 ([phone]).

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

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

   • Assicurati che la priorità dei contenuti multimediali invii prima lo stream degli utenti finali e poi lo stream dei contenuti multimediali dell'operatore umano, perché GTP considera il primo stream di contenuti multimediali come quello degli utenti finali per impostazione predefinita.

   Se ricevi un codice di risposta di errore SIP:

   • Il codice di risposta dell'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 rifiutato) indica probabilmente un problema relativo alla quota. Per informazioni dettagliate su come richiedere un aumento, consulta la pagina Quote e limiti.