Variables d'intégration

En écrivant des expressions, vous pouvez accéder à des variables d'intégration, qui sont des variables contextuelles spécifiques aux intégrations (telles que les intégrations de discussion Web et de téléphone). Toutes les variables d'intégration sont contenues dans l'objet JSON system_integrations, auquel vous pouvez accéder à l'aide de l'expression suivante:

${system_integrations}

L'objet system_integrations a la structure suivante :

{
  "channel": {
    "name": "{channel_name}",
    "private": {
      "user": {
        "id": "{user_id}",
        "phone_number": "{phone_number}",
        "name": "{name}"
      }
    }
  },
  "chat": {...},
  "voice_telephony": {...},
  "text_messaging": {...},
  "whatsapp": {...},
  "slack": {...},
  "facebook": {...},
  "teams": {...}
}

channel

Toujours inclus. Cet objet contient des informations générales sur le canal utilisé pour communiquer avec l'assistant.

Propriétés

Les propriétés contenues dans l'objet private sont traitées comme des variables privées, qui ne sont pas incluses dans les journaux.

Propriétés de l'objet canal
Nom Type Description
channel.name Chaîne

Nom du canal utilisé. Une des valeurs suivantes:

  • Web chat
  • Phone
  • SMS
  • Whatsapp
  • Slack
  • Facebook Messenger
  • teams
channel.private.user.id Chaîne ID de l'utilisateur qui interagit avec l'assistant via le canal. Cet ID est spécifique au canal et peut être différent de l'ID utilisateur utilisé par watsonx Assistant à des fins de facturation. Pour plus d'informations, voir ID utilisateur de canal.
channel.private.user.phone_number Chaîne Numéro de téléphone associé à l'utilisateur. Défini par les intégrations téléphone, SMS et WhatsApp.
channel.private.user.name Chaîne Nom de l'utilisateur qui interagit avec l'assistant via le canal. Défini par l'intégration Microsoft Teams.
channel.private.user.aadObjectId Chaîne ID objet Azure Active Directory (AAD) de l'utilisateur qui interagit avec l'assistant via le canal. Défini par l'intégration Microsoft Teams.

Exemple de JSON

"channel": {
  {
    "name": "Web chat",
    "private": {
      "user": {
        "id": "anonymous_IBMuid-727c0302-6fd7-4abb-b7ee-f06b4bf30e99"
      }
    }
  }
}

ID utilisateur du canal

La propriété channel.private.user.id, qui est définie par l'intégration de canal, spécifie un ID utilisateur pour le client spécifique au canal. La source de cet ID utilisateur dépend du canal:

Sources de l'ID utilisateur du canal
Canal ID utilisateur du canal
Discussion Web ID utilisateur défini par l'instance de discussion Web. Pour plus d'informations, voir Gestion des informations d'identité des utilisateurs dans la discussion Web.
Slack ID membre Slack (par exemple, U2147483697).
Facebook ID de l'expéditeur Facebook (par exemple, 4310101122439797).
WhatsApp Numéro de téléphone du client.
Téléphone Numéro de téléphone du client.
SMS avec Twilio Numéro de téléphone du client.
Equipes L'ID utilisateur Equipes (par exemple, 29:1CV2T75j3QUY-mQCQcIk2...) et indiquez le aadObjectId de l'utilisateur Equipes.

chat

Inclus uniquement si l'intégration de discussion Web est en cours d'utilisation.

Propriétés

Propriétés de l'objet de discussion
Nom Type Description
browser_info.browser_name Chaîne Le nom du navigateur, tel que chrome, edge, ou firefox.
browser_info.browser_version Chaîne Version du navigateur, telle que 109.0.0.
browser_info.browser_OS Chaîne Le système d'exploitation de l'ordinateur du client, tel que Mac OS.
browser_info.language Chaîne Le code local par défaut du navigateur, tel que en-US.
browser_info.page_url Chaîne Le site URL de la page web dans laquelle le chat web est intégré, à l'exclusion de tout paramètre de requête ou de hachage.
browser_info.screen_resolution Chaîne Hauteur et largeur de la fenêtre du navigateur, telle que width: 1440, height: 900.
browser_info.user_agent Chaîne Le contenu de l'en-tête de la requête HTTP User-Agent.
browser_info.client_ip_address Chaîne L'adresse IP de l'ordinateur du client.
browser_info.ip_address_list Tableau Tableau d'annulations des adresses IP spécifiées par les en-têtes de requête HTTP X-Forwarded-For.

Exemple de JSON

"chat": {
  "browser_info": {
    "browser_name": "chrome",
    "browser_version": "109.0.0",
    "browser_OS": "Mac OS",
    "language": "en-US",
    "page_url": "https://us-south.assistant.watson.cloud.ibm.com/crn%3Av1%3Abluemix%3Apublic%3Aconversation%3Aus-south%3Aa%2Fc41400d63d91741a749091dc63574c2c%3Ab696c1e5-7316-4fb0-a61c-664438397e91%3A%3A/assistants/e344fcfe-506c-449f-a182-ebdefe4356ad/actions/actions/custom/edit/action_28584",
    "screen_resolution": "width: 1920, height: 1080",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/109.0.0.0 Safari/537.36",
    "client_ip_address": "65.191.135.254",
    "ip_address_list": [
      "65.191.135.254",
      " 104.99.56.143",
      "10.185.27.136",
      "172.30.226.64"
    ]
  }
},
"channel": {
  "name": "Web chat",
  "private": {
    "user": {
      "id": "anonymous_IBMuid-727c0302-6fd7-4abb-b7ee-f06b4bf30e99"
    }
  }
}

Exemples d'expressions

  • Cette expression teste si le client utilise le navigateur Chrome:

    ${system_integrations}.chat.browser_info.browser_name.equals("chrome")
    

    Vous pouvez spécifier cette expression comme valeur pour une variable de session booléenne, que vous pouvez ensuite utiliser dans une condition d'étape. Par exemple, si votre site Web prend en charge uniquement Chrome, vous pouvez avoir une étape conditionnée sur la variable false et la sortie suivante: I see you aren't using the Chrome browser. Some features of our website work only on Chrome.

  • Cette expression vérifie si la page actuelle URL contient la chaîne payment.html:

    ${system_integrations}.chat.browser_info.page_url.contains("payment.html")
    

    Vous pouvez utiliser cette expression dans une condition d'étape afin d'éviter de demander aux clients d'accéder à une page qu'ils visualisent déjà. Par exemple, dans une action de paiement d'une facture, vous pouvez avoir une étape conditionnée par le fait que cette variable est false et possède la sortie suivante: First, click **Pay bill** to navigate to the bill payment page.

voice_telephony

Inclus uniquement si l'intégration téléphonique est en cours d'utilisation.

L'objet voice_telephony contient des propriétés de réponse et de demande. Les propriétés de demande sont des valeurs définies par l'intégration téléphonique et fournissent des informations sur l'appel. Les propriétés de réponse sont des valeurs d'entrée que vous pouvez modifier dans vos actions pour envoyer des données de journalisation ou pour modifier les options de configuration de l'appel.

Propriétés de demande (définies par l'intégration téléphonique)

Les propriétés contenues dans l'objet private sont traitées comme des variables privées, qui ne sont pas incluses dans les journaux.

Propriétés de demande de l'objet voice_telephony
Nom Type Description
sip_call_id Chaîne L'ID de l'appel SIP associé à l'appel téléphonique.
assistant_phone_number Chaîne Numéro de téléphone associé à la fin watsonx Assistant de l'appel.
sip_custom_invite_headers Objet Tableau défini par l'utilisateur de paires clé / valeur contenant les en-têtes SIP de la demande SIP INVITE.
private.user_phone_number Chaîne Numéro de téléphone d'où provient l'appel du client.
private.sip_request_uri Chaîne URI de la demande SIP entrante qui a lancé l'appel téléphonique.
private.sip_from_uri Chaîne URI de l'en-tête From de la demande SIP.
private.sip_to_uri Chaîne URI de l'en-tête To de la demande SIP.
final_utterance_timeout_occurred Booléen Défini sur true lorsque le délai d'attente de l'énoncé final a été atteint. Ce délai d'attente peut être configuré en envoyant la propriété final_utterance_timeout_count.
post_response_timeout_occurred Booléen Défini sur true lorsque le délai d'attente de l'énoncé final a été atteint. Ce délai d'attente peut être configuré en envoyant la propriété post_response_timeout_count.

Exemple de demande JSON

"voice_telephony": {
  "private":{
    "user_phone_number":"+18595553456",
    "sip_request_uri":"sips:+18885557777@public.voip.us-east.assistant.watson.cloud.ibm.com",
    "sip_from_uri":"sips:+18565558576@twilio.com",
    "sip_to_uri":"sips:+18885557777@public.voip.us-east.assistant.watson.cloud.ibm.com"
  },
  "sip_call_id": "Aob2-2743-5678-1234",
  "assistant_phone_number":"+18885556789",
  "sip_custom_invite_headers": {
    "custom-header1": "123",
    "custom-header2": "456"
  }
}

Vous pouvez accéder aux en-têtes SIP personnalisés en utilisant le format suivant :

${system_integrations.voice_telephony.sip_custom_invite_headers}[<headername>]

Par exemple :

${system_integrations.voice_telephony.sip_custom_invite_headers}["custom-header1"]

renvoie la valeur 123.

Propriétés de réponse (définies par l'assistant)

Propriétés de réponse de l'objet voice_telephony
Nom Type Description
final_utterance_timeout_count Entier Temps (en millisecondes) d'attente d'un énoncé final du service Speech to Text. Si aucun énoncé final n'est reçu avant le dépassement du délai d'attente, l'intégration téléphonique envoie un message à l'assistant avec la propriété final_utterance_timeout_occurred définie sur true.
post_response_timeout_count Entier Temps d'attente (en millisecondes) d'un nouvel énoncé après l'exécution de la dernière réponse. Si aucun énoncé n'est reçu avant le dépassement du délai d'attente, l'intégration téléphonique envoie un message à l'assistant qui inclut la propriété post_response_timeout_occurred définie sur true.
cdr_custom_data Objet Objet JSON contenant des paires clé / valeur à stocker dans l'enregistrement CDR pour l'appel. Chaque fois que cet objet est envoyé, son contenu est fusionné avec les données précédemment envoyées lors de l'appel.
turn_settings.timeout_count Entier Temps d'attente (en millisecondes) pour que watsonx Assistant termine le traitement de chaque échange de conversation.

Exemple de réponse JSON

"voice_telephony" : {
  "post_response_timeout_count":10000,
  "final_utterance_timeout_count":30000,
  "turn_settings": {
    "timeout_count": 5000
  },
  "cdr_custom_data" : {
    "custom_data_1": "data 1",
    "custom_data_2": "data 2"
  }
}

text_messaging

Inclus uniquement si l'intégration SMS avec Twilio est en cours d'utilisation.

Propriétés

Les propriétés contenues dans l'objet private sont traitées comme des variables privées, qui ne sont pas incluses dans les journaux.

Propriétés de l'objet text_messaging
Nom Type Description
assistant_phone_number Chaîne Numéro de téléphone associé à la fin watsonx Assistant de la conversation.
private.user_phone_number Chaîne Numéro de téléphone d'où provient le message SMS du client.

Exemple de JSON

"text_messaging": {
  "private":{
    "user_phone_number":"+18595553456"
  },
  "assistant_phone_number":"+18885556789"
}

whatsapp

Inclus uniquement si l'intégration WhatsApp est en cours d'utilisation.

Propriétés

Les propriétés contenues dans l'objet private sont traitées comme des variables privées, qui ne sont pas incluses dans les journaux.

Propriétés de l'objet whatsapp
Nom Type Description
assistant_phone_number Chaîne Numéro de téléphone associé à la fin watsonx Assistant de la conversation.
private.user_phone_number Chaîne Numéro de téléphone d'où provient le message WhatsApp du client.

Exemple de JSON

"whatsapp": {
  "private":{
    "user_phone_number":"+18595553456"
  },
  "assistant_phone_number":"+18885556789"
}

slack

Inclus uniquement si l'intégration Slack est en cours d'utilisation.

Propriétés

Propriétés de l'objet Slack
Nom Type Description
team_id Chaîne L'identifiant unique de l'équipe Slack.
channel_id Chaîne Identificateur unique du canal Slack.

Exemple de JSON

"slack": {
  "team_id":"T02F3KE542J",
  "channel_id":"C4K3KTTRD"
}

facebook

Inclus uniquement si l'intégration Facebook est en cours d'utilisation.

Propriétés

Aucune propriété supplémentaire.

Exemple de JSON

"facebook": {}

teams

Inclus uniquement si l'intégration Microsoft Teams est en cours d'utilisation.

Propriétés

Propriétés de l'objet équipes
Nom Type Description
conversation_id Chaîne Identificateur unique de la conversation Microsoft Teams.

Exemple de JSON

"teams":{
  "conversation_id":"a:1ATy08jyGkPGy2QdKIrGZL5u_o6fIUVDRKeIZtkIUAkQDC23FC9S97f18i-UNl-eISAfDWqoQeTbregvSE8jK0LNy6h9VssNcN3CsGG9guMiUB0EeSqxnnEFpAVzbkayR"
}