Concetti e risoluzione dei problemi

Questo documento descrive in dettaglio le configurazioni specifiche necessarie per l'integrazione, nonché la risoluzione dei problemi comuni.

Requisiti della rete di telefonia

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

Per la segnalazione SIP, devi consentire l'intero intervallo IP 74.125.88.128/25 (TCP) sulla porta 5672. Per un set di regole firewall più restrittivo, puoi limitare la segnalazione SIP a uno dei seguenti server SIP GTP regionalizzati:

• Regione degli 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. Le porte richieste per i contenuti multimediali sono in genere solo 16384-32767 (TCP+UDP), ma questo intervallo di porte può 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. Puoi trovare istruzioni dettagliate per l'integrazione di ogni fornitore collegato nella versione del firmware.

Fornitori e modelli	Versioni firmware (SIPREC, SIP)
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 minime del firmware supportate che sono state certificate per l'utilizzo 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 multimediali e di segnalazione SBC supportati

Protocollo	Valore
Protocollo di segnalazione	SIP su TLS (SRTP)
Media	SRTP (Secure Real-time Transport Protocol)
Crittografia per contenuti multimediali	SDES (Security Descriptions for SDP)
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. Devi generare dinamicamente l'ID conversazione durante l'INVITE SIP utilizzando il valore dell'intestazione SIP Call-Info o UUI.

Il valore dell'intestazione SIP rimanda all'endpoint Dialogflow definendo l'ID progettoGoogle Cloud e l'ID conversazione:

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 dall'SBC. L'ID conversazione deve essere conforme alla formula dell'espressione regolare [a-zA-Z][a-zA-Z0-9_-]* con una lunghezza dei caratteri compresa tra 3 e 64. Per generare dinamicamente l'ID conversazione, utilizza un pattern comune in cui prendi il valore Call-ID nell'INVITE SIP e lo anteponi a lettere per renderlo conforme all'espressione regolare specificata in precedenza. Ad esempio, se il valore Call-ID è 297363723_79131759_799783510, l'aggiunta del prefisso "CID-" lo renderà conforme all'espressione regolare [a-zA-Z][a-zA-Z0-9_-]*.

Intestazione SIP Call-Info

Aggiungi un'intestazione SIP personalizzata denominata Call-Info al comando 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 è riportata un'intestazione di esempio, 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

Per passare dati aggiuntivi all'agente e impostarli come parametro di sessione, puoi passare un elenco di coppie chiave-valore con codifica esadecimale separate da punto e virgola, seguito da ;encoding=hex;purpose=Goog-Session-Param. In questo modo viene creato un parametro di sessione denominato uui-headers che contiene un elenco di stringhe di payload decodificate.

Ad esempio, se devi trasmettere la stringa key1=value1;key2=value2, viene inviata la seguente intestazione UUI, in cui il payload è il valore con codifica esadecimale di key1=value1;key2=value2:

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

Questa azione crea il seguente parametro di sessione:

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

Se il tuo SBC supporta l'invio di più intestazioni UUI, puoi inviare singole coppie chiave-valore per intestazione UUI per renderle disponibili come singoli valori nel parametro di sessione uui-headers.

Il seguente snippet prende il valore 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)

L'esempio seguente mostra una funzione chiamata da un trigger nei blocchi di codice del playbook, ad esempio @PlaybookStartHandler, che viene chiamata quando si accede al 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 ""

Puoi 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-header SIP

Puoi passare le intestazioni SIP che iniziano con x- all'agente e impostarle come parametro di sessione. Le intestazioni SIP sono disponibili nel parametro di sessione x-headers. Il sistema rimuove il prefisso x- dal nome dell'intestazione nel parametro di sessione.

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

x-billing-id: 12345

Il parametro di sessione x-headers contiene:

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

Per accedere al valore:

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

Passa le informazioni sull'agente umano

Se devi trasmettere informazioni specifiche per gli agenti umani, puoi impostare l'attributo dell'etichetta multimediale del Session Description Protocol (SDP) per lo stream del Real-time Transport Protocol (RTP) dell'agente umano sul valore dei dati richiesto.

Esempio:

a=label:7382373482

Questi dati vengono inseriti nel campo sip_recording_media_label e sono disponibili nell'argomento Pub/Sub New message notification contenente le trascrizioni. Cerca il campo sip_recording_media_label nel messaggio pubsub Message.attributes.

Attenzione: per motivi di conformità, non trasmettere dati utente PII nelle intestazioni SIP. Utilizzale solo per trasmettere coppie chiave-valore non PII.

Configura i ruoli dei partecipanti e l'ordine degli stream multimediali

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

Se hai bisogno di un comportamento diverso, ad esempio per un sistema di chiamate in uscita, devi aggiungere il parametro roles all'URL passato nell'intestazione.

Esempio:

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 SIP Call-Info o UUI.

Imposta parametri aggiuntivi per una determinata conversazione

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

Effettua la chiamata API dopo la risposta 200 OK per l'INVITE SIP iniziale, momento in cui la conversazione è stata creata. L'ID sessione per MatchIntentRequest è lo stesso ID conversazione fornito nell'intestazione Call-Info in INVITE.

Utilizza 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 è simile al seguente esempio:

{
    "sip-refer": true
}

Se devi trasmettere dati da Dialogflow CX, puoi utilizzare le intestazioni UUI e le intestazioni x per trasmettere stringhe di dati. Se vuoi eseguire un'azione SIP REFER e trasmettere 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 viene 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

Utilizza SIP INVITE per effettuare una conferenza con un altro endpoint SIP

Per effettuare una conferenza di 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 puoi utilizzare le funzionalità di Agent Assist. Imposta il campo Telephony transfer call sul numero impostato nel campo SIP INVITE To in uscita.

Se devi trasmettere dati da Dialogflow CX, puoi utilizzare le intestazioni UUI e le intestazioni x per trasmettere stringhe di dati. Se vuoi eseguire un SIP INVITE e trasmettere due coppie chiave-valore in un'intestazione UUI e due x-header, 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"
    }
}

In questo modo viene generato un SIP INVITE con le seguenti intestazioni 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

Trasmetti i dati in un SIP BYE

La navigazione a End Session genera un SIP BYE. Per trasmettere dati da Dialogflow CX, puoi utilizzare le intestazioni UUI o x-header per trasmettere stringhe di dati. Puoi indirizzare la chiamata a una pagina che definisce il payload Live agent handoff simile al seguente esempio di codice prima di passare a End Session:

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

In questo modo viene generato un SIP BYE con le seguenti intestazioni 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

Attiva un'azione quando il chiamante remoto riaggancia

La nuova API BiDi (use_bidi_streaming=True nel profilo di conversazione) 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 sys.remote-call-disconnected. Se crei un gestore con questo nome evento specifico, puoi utilizzarlo per attivare una chiamata allo strumento con un playbook o una chiamata webhook all'interno di un flusso.

Consenti chiamate solo da SBC

Per rifiutare le chiamate dalla rete PSTN e connettere solo le chiamate provenienti dal tuo SBC, aggiorna l'oggetto PhoneNumber per specificare il messaggio allowedSipTrunks. 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 di cui il team di Google Telephony ha eseguito il provisioning.

Risoluzione dei problemi

Il team di Google potrebbe chiederti di fornire i seguenti elementi per aiutarti a risolvere i problemi relativi al ping SIP OPTIONS e alle chiamate di prova:

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

Acquisizione di pacchetti di rete

L'acquisizione dei pacchetti di rete deve mostrare quanto segue:

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

   • La tua rete sta bloccando il traffico in uscita.
   • La comunicazione non viene inviata a uno dei server SIP GTP regionalizzati. Consulta i requisiti di rete per la connettività telefonica.
   • La comunicazione non viene inviata tramite la porta TCP 5672.

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

   • L'SBC avvia TLS v1.2 o versioni successive.
   • L'SBC avvia un "Client Hello" e GTP risponde con "Server Hello".
   • Il processo di autenticazione mutual TLS avviene:
     • GTP risponde con il proprio certificato TLS del server, che viene autenticato dal tuo SBC.
     • L'SBC invia il proprio certificato TLS client, che GTP autentica.
   • Viene stabilito un canale criptato, come dimostrato dal messaggio "Encrypted Handshake Message" nell'acquisizione dei pacchetti.
   • La prova di "Dati applicazioni" viene trasmessa tramite il canale TLS.

   Se non è possibile stabilire una connessione TLS, i possibili problemi includono: - Il trunk SIP non è stato creato sul lato GTP. - Il nome di dominio completo (FQDN) configurato del trunk SIP non corrisponde all'FQDN presentato nel certificato TLS (attributo CN o SAN) dell'SBC. - La versione TLS non è supportata, poiché sono supportate solo le versioni TLS 1.2 o successive: - La suite di crittografia richiesta non è supportata, consulta la configurazione TLS dell'SBC. - Fornitori di certificati TLS non attendibili, consulta 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:

     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
     

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

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

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

   • Invia prima lo stream dell'utente finale, seguito dallo stream multimediale dell'agente umano, perché GTP tratta il primo stream multimediale come l'utente finale per impostazione predefinita.

   Se ricevi un codice di risposta di errore SIP:

   • Un errore SIP di classe 400, ad esempio 488 Non accettabile qui, indica che GTP ha rifiutato un'intestazione SIP o una configurazione SDP dei contenuti multimediali SIP.
   • Un errore SIP di classe 600, ad esempio l'errore SIP 603 Declined, indica un problema relativo alla quota. Consulta la pagina Quote e limiti per i dettagli su come richiedere un aumento.