Concepts et dépannage

Cette page décrit les configurations spécifiques requises pour l'intégration, ainsi que le dépannage des problèmes courants.

Configuration réseau requise pour la téléphonie

Si votre réseau filtre le trafic sortant, il doit autoriser le trafic sortant pour la signalisation SIP et le streaming multimédia.

Pour la signalisation SIP, l'ensemble de la plage d'adresses IP 74.125.88.128/25 (TCP) sur le port 5672 doit être autorisé. Pour un ensemble de règles de pare-feu plus restrictif, vous pouvez limiter la signalisation SIP à un ou plusieurs serveurs GTP SIP régionalisés :

  • Région États-Unis : us.telephony.goog (74.125.88.132)
  • Région Europe : eu.telephony.goog (74.125.88.133)
  • Région APAC : ap.telephony.goog (74.125.88.134)
  • Région Amérique du Sud : sa.telephony.goog (74.125.88.135)

Pour les médias RTP, vous devez configurer des règles de pare-feu afin d'autoriser le trafic destiné à la plage d'adresses IP CIDR 74.125.39.0/24. En règle générale, les ports requis pour les médias sont uniquement 16384-32767 (TCP+UDP). Toutefois, cette plage de ports pourra être étendue à l'avenir.

Fournisseurs ou modèles de SBC compatibles

Le tableau suivant répertorie les fournisseurs ou modèles de SBC compatibles, ainsi que les versions du micrologiciel. Des instructions d'intégration détaillées pour chaque fournisseur sont disponibles dans la version du micrologiciel.

Fournisseurs et modèles Versions du micrologiciel
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)

Protocoles de signalisation et multimédias SBC compatibles
Protocole de signalisation SIP sur TLS
Médias SRTP
Chiffrement multimédia SDES
Suite de chiffrement multimédia compatible AES_CM_128_HMAC_SHA1_80, AEAD_AES_256_GCM
Codecs multimédias compatibles G.711 µ-law (PCMU), G.711 A-law (PCMA), Opus

En-têtes SIP

Lorsque vous avez configuré un profil de conversation et un numéro de téléphone, vous avez créé un profil de conversation CCAI avec le sipConfig.createConversationOnTheFly défini sur true. L'ID de conversation doit être généré de manière dynamique lors de l'invitation SIP à l'aide de la valeur d'en-tête SIP Call-Info ou UUI.

La valeur d'en-tête SIP pointe vers le point de terminaison Dialogflow en définissant l' Google Cloud ID de projet et l'ID de conversation :

  1. L'ID du projet correspond au projet que vous avez utilisé lorsque vous avez configuré un Google Cloud projet. Google Cloud
  2. L'ID de conversation doit être généré de manière dynamique par le SBC. L'ID de conversation doit être conforme à la formule d'expression régulière [a-zA-Z][a-zA-Z0-9_-]* avec une longueur de caractères comprise entre [3,64]. Pour générer dynamiquement l'ID de conversation, un modèle courant consiste à utiliser la valeur Call-ID dans l'invitation SIP et à la préfixer avec des lettres pour la rendre conforme à l'expression régulière, comme indiqué précédemment. Par exemple, si la valeur Call-ID est 297363723_79131759_799783510, la préfixer avec "CID-" la rendrait conforme à l'expression régulière [a-zA-Z][a-zA-Z0-9_-]*.

En-tête SIP Call-Info

Insérez un en-tête SIP personnalisé appelé Call-Info dans l'invitation SIP pour définir de manière unique l'ID de conversation :

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

Exemple :

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

En-tête SIP UUI

Si la configuration de l'en-tête SIP personnalisé Call-Info n'est pas acceptée, vous pouvez configurer l'en-tête SIP UUI (User-to-User) dans l'invitation SIP pour transmettre l'ID de conversation.

Utilisez les mêmes données que celles demandées dans Call-Info avec l'URL encodée au format hexadécimal et l'objectif défini sur Goog-ContactCenter-Conversation. Voici un exemple d'en-tête, où la chaîne hexadécimale, une fois décodée, est 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

Si des données supplémentaires doivent être transmises à l'agent et définies comme paramètre de session, vous pouvez le faire en transmettant une liste de paires clé-valeur séparées par un point-virgule, encodée au format hexadécimal, suivie de ;encoding=hex;purpose=Goog-Session-Param. Un paramètre de session sera alors créé avec le nom uui-headers contenant une liste de chaînes de charge utile décodées.

Par exemple, si la chaîne key1=value1;key2=value2 doit être transmise, l'en-tête UUI suivant est envoyé, où la charge utile est la valeur encodée au format hexadécimal de key1=value1;key2=value2.

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

Le paramètre de session suivant est alors créé.

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

Si votre SBC est compatible avec l'envoi de plusieurs en-têtes UUI, vous pouvez envoyer des chaînes de paires clé-valeur individuelles par en-tête UUI. Elles seront disponibles en tant que valeurs individuelles dans le paramètre de session uui-headers.

L'extrait suivant prend la valeur de paramètre, puis la divise plusieurs fois pour accéder à la valeur appropriée de la variable key2 dans la chaîne.

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

L'exemple suivant montre une fonction appelée à partir d'un déclencheur dans les blocs de code du playbook, par exemple. @PlaybookStartHandler, qui est appelé lors de l'accès au playbook. D'autres fonctions appellent cette fonction pour obtenir des valeurs à partir du paramètre 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 ""

Des données supplémentaires peuvent être envoyées à l'aide d'en-têtes UUI distincts ayant des valeurs "purpose" différentes. Ces valeurs sont ajoutées à l' Conversation.telephonyConnectionInfo objet. Notez que ces données ne sont pas disponibles pour l'agent Dialogflow CX au moment de l'exécution.

En-têtes x-headers SIP

Les en-têtes SIP commençant par x- peuvent être transmis à l'agent et définis comme paramètre de session. Les en-têtes SIP sont disponibles dans le paramètre de session x-headers. Le préfixe x- est supprimé du nom de l'en-tête dans le paramètre de session.

Par exemple, si l'invitation SIP contient l'en-tête suivant :

x-billing-id: 12345

Le paramètre de session x-headers contient :

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

Pour accéder à la valeur :

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

Transmettre des informations sur l'agent humain

Si vous devez transmettre des informations spécifiques aux agents humains, vous pouvez définir l'attribut de libellé multimédia SDP (Session Description Protocol) pour l'agent humain, le flux RTP (Real-time Transport Protocol) sur la valeur de données requise. Exemple: none a=label:7382373482 Ces données seront renseignées dans le champ sip_recording_media_label et disponibles dans la rubrique Pub/Sub New message notification contenant les transcriptions. Recherchez le sip_recording_media_label champ dans le message Message.attributes Pub/Sub.

Configurer les rôles des participants et l'ordre des flux multimédias

Par défaut, le premier flux multimédia est associé au rôle de participant END_USER, et les flux multimédias suivants sont associés au rôle de participant HUMAN_AGENT.

Si vous avez besoin d'un comportement différent (par exemple, dans un système d'appel sortant), l'URL transmise dans l'en-tête doit comporter le paramètre roles.

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

L'URL spécifie que le premier flux multimédia doit avoir le rôle HUMAN_AGENT et que le deuxième flux multimédia doit avoir le rôle END_USER. Vous pouvez appliquer le paramètre roles avec l' Call-Info ou UUI en-tête SIP.

Définir des paramètres supplémentaires pour une conversation donnée

Pour définir des paramètres supplémentaires pour une conversation donnée, utilisez l' MatchIntentRequest appel RPC. Vous pouvez définir query_params.parameters sur les paires clé-valeur requises et query_input.text sur une valeur telle que "Setting parameters" (Définition des paramètres).

Effectuez l'appel d'API après la réponse 200 OK pour l'invitation SIP initiale, moment où la conversation a été créée. L'ID de session pour MatchIntentRequest est le même ID de conversation que celui fourni dans l'en-tête Call-Info de l'invitation.

Utiliser SIP REFER pour transférer un appel vers un point de terminaison SIP

Pour transférer un appel d'un agent virtuel vers un point de terminaison SIP, utilisez la méthode SIP REFER. Incluez une charge utile dans le champ Live agent handoff et définissez le champ Telephony transfer call sur le numéro défini dans le champ Refer-To SIP REFER sortant. Votre charge utile Live agent handoff doit ressembler à l'exemple de code suivant.

{
    "sip-refer": true
}

Si des données doivent être transmises en dehors de Dialogflow CX, les en-têtes UUI et x-headers peuvent être utilisés pour transmettre des chaînes de données. Si vous souhaitez effectuer une SIP REFER et transmettre deux paires clé-valeur dans un en-tête UUI et deux en-têtes x-headers, vous pouvez utiliser une charge utile Live agent handoff semblable à l'exemple de code suivant.

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

Un SIP REFER est alors généré avec les en-têtes UUI et x-headers suivants.

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

Utiliser SIP INVITE pour mettre en conférence un appel avec un autre point de terminaison SIP

Pour mettre en conférence un appel d'un client final à un agent humain accessible à l'aide d'un point de terminaison SIP, utilisez la méthode SIP INVITE. Google reste ainsi dans le chemin multimédia et permet d'utiliser les fonctionnalités d'Agent Assist. Définissez le champ Telephony transfer call sur le numéro défini dans le champ To SIP INVITE sortant.

Si des données doivent être transmises en dehors de Dialogflow CX, les en-têtes UUI et x-headers peuvent être utilisés pour transmettre des chaînes de données. Si vous souhaitez effectuer une SIP INVITE et transmettre deux paires clé-valeur dans un en-tête UUI et deux en-têtes x-headers, vous pouvez utiliser une charge utile Live agent handoff semblable à l'exemple de code suivant.

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

Un SIP INVITE est alors généré avec les en-têtes UUI et x-headers suivants.

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

Transmettre des données dans un SIP BYE

L'accès à End Session déclenche un SIP BYE. Si vous souhaitez transmettre des données en dehors de Dialogflow CX, les en-têtes UUI ou x-headers peuvent être utilisés pour transmettre des chaînes de données. Vous devez acheminer l'appel vers une page qui définit la charge utile Live agent handoff semblable à l'exemple de code suivant avant de passer à End Session.

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

Un SIP BYE est alors généré avec les en-têtes UUI et x-headers suivants.

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

Déclencher une action lorsque l'appelant distant raccroche

La nouvelle API BiDi (use_bidi_streaming=True dans ConversationProfile) permet de déclencher un appel d'outil dans un playbook ou un appel de webhook dans un flux lorsque l'appelant distant raccroche.

Lorsque l'appelant distant raccroche et que Dialogflow CX reçoit un message SIP BYE, l'événement personnalisé sys.remote-call-disconnected est déclenché. Si vous créez un gestionnaire avec ce nom d'événement spécifique, vous pouvez ensuite l'utiliser pour déclencher un appel d'outil avec un playbook ou un appel de webhook dans un flux.

Autoriser les appels uniquement à partir du SBC

Pour refuser les appels provenant du RTC et ne connecter que les appels provenant de votre SBC, mettez à jour l' PhoneNumber objet afin de spécifier le allowedSipTrunks message. Si l'intégration utilise une jonction SIP, vous pouvez spécifier une liste d'ID de jonction SIP spécifiques. Si le message est créé avec une liste vide, toute jonction SIP est autorisée. Si une interconnexion privée est établie, fournissez l'ID d'opérateur provisionné par l'équipe Google Telephony.

Dépannage

L'équipe Google peut vous demander de fournir les artefacts suivants pour faciliter le dépannage du ping SIP OPTIONS et des appels de test effectués :

  1. Capture de paquets réseau
  2. Trace de débogage SIP affichant l'en-tête complet et le SDP SIP :
    • Valeur Call-ID
    • Valeur Call-Info (si elle existe)

Capture de paquets réseau

La capture de paquets réseau doit afficher les éléments suivants :

  1. Un handshake TCP complet en trois étapes (SYN, SYN-ACK, ACK) entre votre SBC et les serveurs GTP SIP communiquant via le port TCP 5672. Si la connexion TCP n'a pas pu être établie, les problèmes possibles sont les suivants :

  2. Un handshake de connexion TLS complet avec les éléments suivants :

    • TLS v1.2 ou version ultérieure initiée par votre SBC.
    • Votre SBC lance un "Client Hello" et GTP répond avec "Server Hello".
    • Processus d'authentification TLS mutuelle.
      • GTP répond avec son propre certificat TLS de serveur, qui est authentifié par votre SBC.
      • Le SBC envoie son propre certificat TLS client, qui est authentifié par GTP.
    • Canal chiffré établi, comme en témoigne le message "Encrypted Handshake Message".
    • Preuve de la transmission de "Application Data" sur le canal TLS.

    Si la connexion TLS n'a pas pu être établie, les problèmes possibles sont les suivants :

    • La jonction SIP n'a pas été créée côté GTP.
    • Le nom de domaine complet configuré de la jonction SIP ne correspond pas au nom de domaine complet présenté dans le certificat TLS (attribut CN ou SAN) du SBC.
    • La version de TLS n'est pas compatible. Seules les versions 1.2 ou ultérieures de TLS sont compatibles.
    • La suite de chiffrement demandée n'est pas compatible. Consultez la section Configuration TLS du SBC.
    • Fournisseurs de certificats TLS non fiables. Consultez la section Configuration TLS du SBC.

  3. La trace de débogage SIP doit afficher les éléments suivants :

    • En-tête SIP Call-Info du client inséré au format suivant : none Call-Info: <http://dialogflow.googleapis.com/v2beta1/projects/$PROJECT_ID/conversations/$CONVERSATION_ID>;purpose=Goog-ContactCenter-Conversation

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

    • Les en-têtes SIP affichent le numéro de téléphone au format E.164 (+16501234567).

    • Les en-têtes SIP affichent les adresses IP publiques utilisées dans l'URI de la demande et d'autres champs d'en-tête SIP (par exemple, To, From, Via). Les adresses IP privées sont refusées.

    • Les informations de connexion SDP SIP (c= ... ) sont spécifiées avec une adresse IP publique. Les adresses IP privées sont refusées.

    • Assurez-vous que la priorité des médias envoie d'abord le flux des utilisateurs finaux, puis le flux multimédia de l'agent humain, car GTP traite le premier flux multimédia comme celui des utilisateurs finaux par défaut.

    Si vous recevez un code de réponse d'erreur SIP :

    • Le code de réponse d'erreur SIP 400 (par exemple, 488 Not Acceptable Here) indique probablement que GTP a refusé un en-tête SIP ou une configuration SDP multimédia SIP.
    • Le code de réponse d'erreur SIP 600 (erreur SIP 603 Declined) indique probablement un problème lié aux quotas. Pour savoir comment demander une augmentation, consultez la page Quotas et limites.