Concepts et dépannage

Cette page décrit en détail les configurations spécifiques requises pour l'intégration et 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 SIP GTP régionalisés :

  • Région des États-Unis : us.telephony.goog (74.125.88.132)
  • Région de l'UE : 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 général, les ports requis pour les contenus multimé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 liste les fournisseurs ou modèles de SBC et les versions de micrologiciel compatibles. 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.40A.500.786
Avaya Session Border Controller for Enterprise v8.1.3.2-38-22279, v10.2.0.0-86-24077
Oracle E-SBC Acme Packet 3900 SCZ9.3.0 GA (Build 46)
Ribbon Swe Core SBC v11.01.01R005
Cisco Unified Border Element (CUBE) v17.15.03a

Protocoles de signalisation et multimédias SBC compatibles
Protocole de signalisation SIP sur TLS
Médias SRTP
Chiffrement des contenus multimédias SDES
Suite de chiffrement multimédia acceptée 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 configurez un profil de conversation et un numéro de téléphone, vous créez un profil de conversation CCAI avec sipConfig.createConversationOnTheFly défini sur true. L'ID de conversation doit être généré de manière dynamique lors de l'INVITE SIP en utilisant la valeur de l'en-tête SIP de Call-Info ou UUI.

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

  1. L'ID de projet Google Cloud correspond au projet que vous avez utilisé lorsque vous avez configuré un 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 à l'expression régulière [a-zA-Z][a-zA-Z0-9_-]*, avec une longueur de caractères comprise dans la plage [3,64]. Pour générer dynamiquement l'ID de conversation, un modèle courant consiste à utiliser la valeur Call-ID dans le SIP INVITE et à la préfixer avec des lettres pour la rendre conforme à l'expression régulière spécifiée précédemment. Par exemple, si la valeur de l'ID d'appel est 297363723_79131759_799783510, le fait de la préfixer avec "CID-" la rendra 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 le SIP INVITE 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 prise en charge, vous pouvez configurer l'en-tête SIP UUI (User-to-User) dans le SIP INVITE pour transmettre l'ID de conversation.

Utilisez les mêmes données que celles demandées dans Call-Info, avec l'URL encodée en 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 conversationnel 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 et encodées en hexadécimal, suivie de ;encoding=hex;purpose=Goog-Session-Param. Un paramètre de session sera alors créé avec le nom uui-headers et contiendra 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 sera envoyé, où la charge utile est la valeur encodée en 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 valeurs clés 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 du paramètre, puis le 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'entrée dans le 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'objet Conversation.telephonyConnectionInfo. Notez que ces données ne sont pas disponibles pour l'agent Agents de conversation (Dialogflow CX) au moment de l'exécution.

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é média du protocole de description de session (SDP) pour le flux RTP (Real-time Transport Protocol) de l'agent humain 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 le sujet Pub/Sub New message notification contenant les transcriptions. Recherchez le champ sip_recording_media_label 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" en annexe.

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

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

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

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

Effectuez l'appel d'API après la réponse "200 OK" pour l'INVITE SIP initial, au 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'INVITE.

Utilisez 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 nombre défini dans le champ Refer-To SIP REFER sortant. Votre charge utile doit ressembler à l'exemple de code suivant.

{
    "sip-refer": true
}

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

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

Cela générerait un SIP REFER avec l'en-tête UUI suivant.

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

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 montrant l'en-tête complet et le SDP SIP :
    • Valeur Call-ID
    • Valeur Call-Info (le cas échéant)

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 SIP GTP, communiqué 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é par votre SBC.
    • Votre SBC lance un "Client Hello" et GTP répond avec un "Server Hello".
    • Processus d'authentification TLS mutuelle.
      • Le 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.
    • Un canal chiffré a été établi, comme l'indique le message "Encrypted Handshake Message" (Message de handshake chiffré).
    • Preuve de la transmission des "données d'application" 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é du trunk SIP ne correspond pas à celui présenté dans le certificat TLS (attribut CN ou SAN) du SBC.
    • La version TLS n'est pas compatible. Seules les versions 1.2 ou ultérieures sont acceptées.
    • La suite de chiffrement demandée n'est pas compatible. Consultez la section Configuration TLS du SBC.
    • Pour en savoir plus sur les fournisseurs de certificats TLS non fiables, consultez Configuration TLS du SBC.

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

    • En-tête SIP du client Call-Info 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 requête et d'autres champs d'en-tête SIP (par exemple, "To", "From", "Via"). Les adresses IP privées seront refusées.

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

    • Assurez-vous que la hiérarchisation des contenus multimédias envoie d'abord le flux de l'utilisateur final, puis le flux multimédia de l'agent humain, car GTP traite le premier flux multimédia comme celui de l'utilisateur final 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 média SIP.
    • Un code de réponse d'erreur SIP 600 (erreur SIP 603 "Refusé") indique probablement un problème lié au quota. Pour savoir comment demander une augmentation, consultez la page Quotas et limites.

Déclencher une action lorsque l'appelant à distance 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 à distance raccroche et que les agents conversationnels (Dialogflow CX) reçoivent 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.