Konzepte und Fehlerbehebung

Auf dieser Seite werden bestimmte Konfigurationen beschrieben, die für die Integration erforderlich sind, sowie Informationen zur Fehlerbehebung bei häufigen Problemen.

Anforderungen an das Telefonienetzwerk

Wenn Ihr Netzwerk ausgehenden Traffic filtert, muss es ausgehenden Traffic für die SIP-Signalisierung und das Media-Streaming zulassen.

Für die SIP-Signalisierung sollte der gesamte IP-Bereich 74.125.88.128/25 (TCP) über Port 5672 zulässig sein. Für eine restriktivere Firewallregel können Sie die SIP-Signalisierung auf einen oder mehrere regionalisierte GTP-SIP-Server beschränken:

• Region USA: us.telephony.goog (74.125.88.132)
• Region EU: eu.telephony.goog (74.125.88.133)
• Region APAC: ap.telephony.goog (74.125.88.134)
• Region Südamerika: sa.telephony.goog (74.125.88.135)

Für RTP-Medien müssen Sie Firewallregeln konfigurieren, um Traffic zuzulassen, der für den CIDR-IP-Bereich 74.125.39.0/24 bestimmt ist. In der Regel sind für Medien nur die Ports 16384–32767 (TCP+UDP) erforderlich. Dieser Portbereich kann jedoch in Zukunft erweitert werden.

Unterstützte SBC-Anbieter oder -Modelle

In der folgenden Tabelle sind die unterstützten SBC-Anbieter oder -Modelle und Firmwareversionen aufgeführt. Detaillierte Integrationsanleitungen für jeden Anbieter sind in der Firmwareversion verlinkt.

Anbieter und Modelle	Firmwareversionen
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)

Hinweis: Diese Tabelle enthält die mindestens unterstützten Firmwareversionen, die für die Verwendung mit der SIP-Integration zertifiziert wurden. Außerdem sind neuere Firmwareversionen, die zu dieser großen Firmware-Patch-Reihe gehören, zertifiziert.

Unterstützte SBC-Signalisierungs- und Medienprotokolle

Signalisierungsprotokoll	SIP über TLS
Medien	SRTP
Medienverschlüsselung	SDES
Unterstützte Medien-Cipher-Suite	AES_CM_128_HMAC_SHA1_80, AEAD_AES_256_GCM
Unterstützte Medien-Codecs	G.711 µ-law (PCMU), G.711 A-law (PCMA), Opus

SIP-Header

Wenn Sie ein Unterhaltungsprofil und eine Telefonnummer einrichten, haben Sie ein CCAI-Unterhaltungsprofil erstellt, bei dem sipConfig.createConversationOnTheFly auf true gesetzt ist. Die Unterhaltungs-ID sollte während der SIP-INVITE-Nachricht dynamisch generiert werden, indem der SIP-Headerwert von Call-Info oder UUI verwendet wird.

Der SIP-Headerwert verweist auf den Dialogflow-Endpunkt, indem die Google Cloud Projekt-ID und die Unterhaltungs-ID definiert werden:

1. Die Google Cloud Projekt-ID ist das Projekt, das Sie beim Einrichten eines Google Cloud Projekts verwendet haben.
2. Die Unterhaltungs-ID sollte dynamisch vom SBC generiert werden. Die Unterhaltungs-ID muss der Formel für reguläre Ausdrücke [a-zA-Z][a-zA-Z0-9_-]* entsprechen und die Zeichenlänge muss im Bereich von [3,64] liegen. Ein gängiges Muster zum dynamischen Generieren der Unterhaltungs-ID besteht darin, den Call-ID-Wert in der SIP-INVITE-Nachricht zu verwenden und ihm Buchstaben voranzustellen, damit er der zuvor angegebenen Formel für reguläre Ausdrücke entspricht. Wenn der Call-ID-Wert beispielsweise 297363723_79131759_799783510 ist, würde das Voranstellen von "CID-" den Wert mit der Formel für reguläre Ausdrücke [a-zA-Z][a-zA-Z0-9_-]* kompatibel machen.

Call-Info-SIP-Header

Fügen Sie in die SIP-INVITE-Nachricht einen benutzerdefinierten SIP-Header namens Call-Info ein, um die Unterhaltungs-ID eindeutig festzulegen:

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

Beispiel:

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

UUI-SIP-Header

Wenn das Festlegen des benutzerdefinierten SIP-Headers Call-Info nicht unterstützt wird, können Sie den SIP-Header UUI (User-to-User) in der SIP-INVITE-Nachricht konfigurieren, um die Unterhaltungs-ID zu übergeben.

Verwenden Sie dieselben Daten, die in Call-Info angefordert wurden, wobei die URL hexadezimal codiert und der Zweck auf Goog-ContactCenter-Conversation festgelegt ist. Das folgende Beispiel zeigt einen Header, bei dem der Hex-String nach der Decodierung http://dialogflow.googleapis.com/v2beta1/projects/gcp-project-id-12345/conversations/CID-297363723_79131759_799783510 ist:

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

Wenn zusätzliche Daten an den Agent übergeben und als Sitzungsparameter festgelegt werden müssen, können Sie eine durch Semikolons getrennte Liste von Schlüssel-Wert-Paaren übergeben, die hexadezimal codiert ist, gefolgt von ;encoding=hex;purpose=Goog-Session-Param. Dadurch wird ein Sitzungsparameter mit dem Namen uui-headers erstellt, der eine Liste decodierter Nutzlaststrings enthält.

Wenn beispielsweise der String key1=value1;key2=value2 übergeben werden muss, wird der folgende UUI-Header gesendet, wobei die Nutzlast der hexadezimal codierte Wert von key1=value1;key2=value2 ist.

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

Dadurch wird der folgende Sitzungsparameter erstellt.

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

Wenn Ihr SBC das Senden mehrerer UUI-Header unterstützt, können Sie für jeden UUI-Header einzelne Schlüssel-Wert-Strings senden. Diese sind dann als einzelne Werte im Sitzungsparameter uui-headers verfügbar.

Das folgende Snippet verwendet den Parameterwert und teilt den Parameter dann mehrmals auf, um auf den entsprechenden Wert für die Variable key2 im String zuzugreifen.

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

Das folgende Beispiel zeigt eine Funktion, die von einem Trigger in den Codeblöcken des Playbooks aufgerufen wird, z. B. @PlaybookStartHandler, der beim Aufrufen des Playbooks aufgerufen wird. Andere Funktionen rufen diese Funktion auf, um Werte aus dem Parameter uui-headers abzurufen.

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

Zusätzliche Daten können mit separaten UUI-Headern mit unterschiedlichen „purpose“-Werten gesendet werden. Diese Werte werden dem Conversation.telephonyConnectionInfo Objekt hinzugefügt. Beachten Sie, dass diese Daten zur Laufzeit nicht für den Dialogflow CX-Agent verfügbar sind.

SIP-X-Header

SIP-Header, die mit x- beginnen, können an den Agent übergeben und als Sitzungsparameter festgelegt werden. Die SIP-Header sind im Sitzungsparameter x-headers verfügbar. Das Präfix x- wird im Sitzungsparameter aus dem Headernamen entfernt.

Wenn die SIP-INVITE-Nachricht beispielsweise den folgenden Header enthält:

x-billing-id: 12345

Der Sitzungsparameter x-headers enthält:

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

So greifen Sie auf den Wert zu:

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

Informationen zum Kundenservicemitarbeiter übergeben

Wenn Sie Informationen übergeben müssen, die speziell für Kundenservicemitarbeiter gelten, können Sie das SDP-Medienlabelattribut (Session Description Protocol) für den RTP-Stream (Real-time Transport Protocol) des Kundenservicemitarbeiters auf den erforderlichen Datenwert festlegen. Beispiel: none a=label:7382373482 Diese Daten werden in das sip_recording_media_label Feld eingefügt und sind im New message notification Pub/Sub-Thema verfügbar, das die Transkripte enthält. Suchen Sie in der Pub/Sub-Message.attributes Nachricht nach dem sip_recording_media_label Feld.

Warnung: Aus Compliance-Gründen dürfen in SIP-Headern keine personenbezogenen Daten übergeben werden. Sie sollten nur verwendet werden, um Schlüssel-Wert-Paare zu übergeben, die keine personenbezogenen Daten enthalten.

Teilnehmerrollen und Reihenfolge der Media-Streams konfigurieren

Standardmäßig ist der erste Media-Stream der Teilnehmerrolle END_USER zugeordnet und die nachfolgenden Media-Streams der Teilnehmerrolle HUMAN_AGENT.

Wenn Sie ein anderes Verhalten benötigen (z. B. in einem System für ausgehende Anrufe), muss die im Header übergebene URL den Parameter „roles“ enthalten.

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

Die URL gibt an, dass der erste Media-Stream die Rolle HUMAN_AGENT und der zweite Media-Stream die Rolle END_USER haben soll. Sie können den Parameter „roles“ mit dem Call-Info oder UUI SIP-Header anwenden.

Zusätzliche Parameter für eine bestimmte Unterhaltung festlegen

Verwenden Sie den MatchIntentRequest RPC-Aufruf, um zusätzliche Parameter für eine bestimmte Unterhaltung festzulegen. Sie können query_params.parameters auf die erforderlichen Schlüssel-Wert-Paare und query_input.text auf etwas wie „Parameter festlegen“ setzen.

Führen Sie den API-Aufruf nach der Antwort „200 OK“ für die erste SIP-INVITE-Nachricht aus. Zu diesem Zeitpunkt wurde die Unterhaltung erstellt. Die Sitzungs-ID für MatchIntentRequest ist dieselbe Unterhaltungs-ID, die in der INVITE-Nachricht im Header Call-Info angegeben wurde.

SIP REFER verwenden, um einen Anruf an einen SIP-Endpunkt weiterzuleiten

Verwenden Sie die SIP-REFER-Methode, um einen Anruf von einem virtuellen Agent an einen SIP-Endpunkt weiterzuleiten. Fügen Sie eine Nutzlast in das Feld Live agent handoff ein und legen Sie das Feld Telephony transfer call auf die Nummer fest, die im ausgehenden SIP REFER-Feld Refer-To festgelegt ist. Ihre Live agent handoff-Nutzlast sollte in etwa so aussehen wie im folgenden Codebeispiel.

{
    "sip-refer": true
}

Wenn Daten aus Dialogflow CX übergeben werden müssen, können UUI-Header und X-Header verwendet werden, um Datenstrings zu übergeben. Wenn Sie eine SIP REFER-Nachricht senden und zwei Schlüssel-Wert-Paare in einem UUI-Header und zwei X-Header übergeben möchten, können Sie eine Live agent handoff-Nutzlast verwenden, die dem folgenden Codebeispiel ähnelt.

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

Dadurch wird eine SIP-REFER-Nachricht mit den folgenden UUI- und X-Headern generiert.

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

SIP INVITE verwenden, um einen Anruf mit einem anderen SIP-Endpunkt zu konferieren

Verwenden Sie die SIP-INVITE-Methode, um einen Anruf von einem Endkunden an einen Kundenservicemitarbeiter zu konferieren, der über einen SIP-Endpunkt erreichbar ist. Dadurch bleibt Google im Medienpfad und die Funktionen von Agent Assist können verwendet werden. Legen Sie das Feld Telephony transfer call auf die Nummer fest, die im ausgehenden SIP INVITE-Feld To festgelegt ist.

Wenn Daten aus Dialogflow CX übergeben werden müssen, können UUI-Header und X-Header verwendet werden, um Datenstrings zu übergeben. Wenn Sie eine SIP INVITE-Nachricht senden und zwei Schlüssel-Wert-Paare in einem UUI-Header und zwei X-Header übergeben möchten, können Sie eine Live agent handoff-Nutzlast verwenden, die dem folgenden Codebeispiel ähnelt.

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

Dadurch wird eine SIP-INVITE-Nachricht mit den folgenden UUI- und X-Headern generiert.

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

Daten in einer SIP-BYE-Nachricht übergeben

Wenn Sie zu End Session navigieren, wird eine SIP-BYE-Nachricht ausgelöst. Wenn Sie Daten aus Dialogflow CX übergeben möchten, können Sie UUI-Header oder X-Header verwenden, um Datenstrings zu übergeben. Sie würden den Anruf an eine Seite weiterleiten, auf der die Live agent handoff-Nutzlast ähnlich dem folgenden Codebeispiel definiert ist, bevor Sie zu End Session wechseln.

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

Dadurch wird eine SIP-BYE-Nachricht mit den folgenden UUI- und X-Headern generiert.

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

Aktion auslösen, wenn der Remote-Anrufer auflegt

Die neue BiDi API (use_bidi_streaming=True im ConversationProfile) unterstützt das Auslösen eines Tool-Aufrufs in einem Playbook oder eines Webhook-Aufrufs in einem Flow, wenn der Remote-Anrufer auflegt.

Wenn der Remote-Anrufer auflegt und Dialogflow CX eine SIP-BYE-Nachricht empfängt, wird das benutzerdefinierte Ereignis sys.remote-call-disconnected ausgelöst. Wenn Sie einen Handler mit diesem bestimmten Ereignisnamen erstellen, können Sie ihn verwenden, um einen Tool-Aufruf mit einem Playbook oder einen Webhook-Aufruf in einem Flow auszulösen.

Nur Anrufe vom SBC zulassen

Wenn Sie Anrufe aus dem PSTN ablehnen und nur Anrufe von Ihrem SBC zulassen möchten, aktualisieren Sie das PhoneNumber Objekt, um die allowedSipTrunks Nachricht anzugeben. Wenn die Integration einen SIP-Trunk verwendet, können Sie eine Liste bestimmter SIP-Trunk-IDs angeben. Wenn die Nachricht mit einer leeren Liste erstellt wird, ist jeder SIP-Trunk zulässig. Wenn eine private Verbindung hergestellt wird, geben Sie die vom Google Telephony-Team bereitgestellte Carrier-ID an.

Fehlerbehebung

Das Google-Team fordert Sie möglicherweise auf, die folgenden Artefakte zur Unterstützung der Fehlerbehebung beim SIP-OPTIONS-Ping und bei den durchgeführten Testanrufen bereitzustellen:

1. Netzwerkpaketerfassung
2. SIP-Debug-Trace mit vollständigem Header und SIP-SDP:
   • Call-ID-Wert
   • Call-Info-Wert (falls vorhanden)

Netzwerkpaketerfassung

Die Netzwerkpaketerfassung sollte Folgendes zeigen:

1. Ein vollständiger 3-Wege-TCP-Handshake (SYN, SYN-ACK, ACK) zwischen Ihrem SBC und den GTP-SIP-Servern, die über den TCP-Port 5672 kommunizieren. Wenn keine TCP-Verbindung hergestellt werden konnte, können folgende Probleme vorliegen:

   • Ihr Netzwerk blockiert ausgehenden Traffic.
   • Die Kommunikation wird nicht an einen der regionalisierten GTP-SIP-Server gesendet. Weitere Informationen finden Sie unter Netzwerkanforderung für die Telefonieverbindung.
   • Die Kommunikation wird nicht über den TCP-Port 5672 gesendet.

2. Ein vollständiger TLS-Verbindungs-Handshake mit Folgendem:

   • TLS v1.2 oder höher, initiiert von Ihrem SBC.
   • Ihr SBC initiiert ein „Client Hello“ und GTP antwortet mit „Server Hello“.
   • Gegenseitige TLS-Authentifizierung.
     • GTP antwortet mit seinem eigenen TLS-Serverzertifikat, das von Ihrem SBC authentifiziert wird.
     • Der SBC sendet sein eigenes TLS-Clientzertifikat, das von GTP authentifiziert wird.
   • Verschlüsselter Kanal, wie durch „Encrypted Handshake Message“ belegt.
   • Nachweis, dass „Application Data“ über den TLS-Kanal übertragen wird.

   Wenn keine TLS-Verbindung hergestellt werden konnte, können folgende Probleme vorliegen:

   • Auf der GTP-Seite wurde kein SIP-Trunk erstellt.
   • Der konfigurierte FQDN des SIP-Trunks stimmt nicht mit dem FQDN überein, der im TLS-Zertifikat (CN- oder SAN-Attribut) vom SBC präsentiert wird.
   • Die TLS-Version wird nicht unterstützt. Es werden nur TLS-Version 1.2 oder höher unterstützt.
   • Die angeforderte Cipher-Suite wird nicht unterstützt. Weitere Informationen finden Sie unter TLS-Konfiguration des SBC.
   • Nicht vertrauenswürdige TLS-Zertifikatanbieter. Weitere Informationen finden Sie unter TLS-Konfiguration des SBC.

3. Der SIP-Debug-Trace sollte Folgendes zeigen:

   • Der Kunde Call-Info SIP-Header wurde in diesem Format eingefügt: none Call-Info: <http://dialogflow.googleapis.com/v2beta1/projects/$PROJECT_ID/conversations/$CONVERSATION_ID>;purpose=Goog-ContactCenter-Conversation

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

   • Die SIP-Header zeigen die Telefonnummer im E.164-Format ([phone]).

   • Die SIP-Header zeigen öffentliche IP-Adressen, die in der Anfrage-URI und anderen SIP-Headerfeldern verwendet werden (z. B. „To“, „From“, „Via“). Private IP-Adressen werden abgelehnt.

   • Die SIP-SDP-Verbindungsinformationen (c= ... ) werden mit einer öffentlichen IP-Adresse angegeben. Private IP-Adressen werden abgelehnt.

   • Achten Sie darauf, dass bei der Medienpriorisierung zuerst der Stream des Endnutzers und dann der Media-Stream des Kundenservicemitarbeiters gesendet wird, da GTP den ersten Media-Stream standardmäßig als den des Endnutzers behandelt.

   Wenn Sie einen SIP-Fehlerantwortcode erhalten:

   • Der SIP-Fehlercode 400 (z. B. 488 Not Acceptable Here) weist wahrscheinlich darauf hin, dass GTP eine SIP-Header- oder SIP-Media-SDP-Konfiguration abgelehnt hat.
   • Der SIP-Fehlercode 600 (SIP 603 Declined Error) weist wahrscheinlich auf ein Problem mit dem Kontingent hin. Auf der Seite Kontingente und Limits finden Sie Informationen zum Anfordern einer Erhöhung.