Intégrations de scripts

Vous pouvez créer vos propres actions de bot dans Bot Builder. Vous pouvez ainsi personnaliser la façon dont votre bot réagit dans les conversations. Les actions de bot sont utilisées dans les dialoguesFermé Histoires et règles des robots dans Bot Builder. afin de définir les réponses du bot pendant les conversations.

Les actions personnalisées sont créées en tant qu'intégrations de scripts dans Bot Builder. Les intégrations de scripts prennent en charge JavaScript. Chaque intégration de script peut comporter plusieurs actions. Lorsque cette option est activée, les actions personnalisées sont disponibles dans la liste des actions du bot lorsque vous ajoutez une réponse du robot à une histoireFermé Utilisé pour former le bot à la gestion des interactions en fonction de l'intention et du contexte, une règleFermé Utilisé pour définir la réponse du bot aux messages qui ne changent pas avec le contexte. ou une solution de repliFermé Ces sites sont destinés au développement et à l’assistance de CXone, et pas à son fonctionnement. Leur blocage peut entraver l'accès aux liens d'aide et de téléchargement de la plate-forme..

La liste suivante présente des exemples d'utilisation des actions personnalisées des bots :

  • Rédiger du code pour concevoir des actions de bots afin de répondre aux besoins uniques de votre organisation.
  • Appeler votre propre API externe en tant qu'action de bot.
  • Ajouter des scripts dans les compétences de bot et les publier dans Skill Store.

Comme les scripts Bot Builder fonctionnent sur le serveur, certaines limitations sont à prendre en compte lors de la rédaction des scripts.

Éditeur de scripts

Une intégration de script peut comporter plusieurs actions. Chaque d’action possède son propre script. Vous pouvez accéder à l'éditeur de scripts à partir des propriétés de chaque action.

L'onglet Scripts de la section Intégrations, montrant la page principale avec les actions et les variables.

Dans l'éditeur, vous pouvez saisir du code à gauche, puis cliquer sur le triangle d'exécution Une flèche triangulaire pointant vers la droite. afin d’afficher les résultats dans le volet Console.

L’onglet Scripts de la section Intégrations, où vous pouvez écrire du code JavaScript personnalisé à gauche et voir le code exécuté à droite.

Variables de script

Vous pouvez créer des variables afin de les utiliser dans des scripts Bot Builder. Les variables peuvent stocker une valeur qui sera utilisée ailleurs dans le script. Elles ne peuvent être utilisées que dans l'intégration de scripts où vous les créez, mais vous pouvez les utiliser dans tous les scripts de cette intégration.

Les valeurs des variables ne peuvent pas être modifiées dans le script. Elles ne peuvent être modifiées que sur la page d'intégration du script ou lorsqu'une action faisant référence à la variable est utilisée dans une réponse du bot dans une histoireFermé Utilisé pour former le bot à la gestion des interactions en fonction de l'intention et du contexte, une règleFermé Utilisé pour définir la réponse du bot aux messages qui ne changent pas avec le contexte. ou une solution de repliFermé Ces sites sont destinés au développement et à l’assistance de CXone, et pas à son fonctionnement. Leur blocage peut entraver l'accès aux liens d'aide et de téléchargement de la plate-forme..

Pour utiliser une variable dans une action :

  • Le script de l'action doit faire référence à la variable.
  • Elle doit être rendue modifiable dans cette action, si vous voulez pouvoir modifier la valeur.

Les scriptsBot Builder prennent en charge quatre types de variables :

  • Texte : les variables de type Texte contiennent des valeurs de chaînes simples. Une variable Texte modifiable devient un champ dans l'interface utilisateur de l'action personnalisée du bot, dans lequel vous pouvez saisir du texte pour attribuer une valeur à la variable.
  • Nombre : les variables de type Nombre contiennent des valeurs numériques. Une variable Nombre modifiable devient un champ dans l'interface utilisateur de l'action personnalisée du bot, dans lequel vous pouvez saisir un nombre pour attribuer une valeur à la variable.
  • Sélection : Utilisez les variables de type Sélection lorsque vous voulez définir plusieurs valeurs possibles pour la variable. Une variable Sélection devient une liste déroulante dans l'interface utilisateur de l'action personnalisée du bot. Les options de la liste déroulante sont définies dans le champ Valeurs de la définition de la variable dans l'onglet Scripts.
  • Secret : utilisez des variables de type Secret pour stocker des données privées, telles que des jetons ou des identifiants d'API. Après avoir saisi la valeur, Bot Builder masque tous les caractères, sauf les cinq premiers, à l’aide d’astérisques ( * ). La valeur est en lecture seule et ne peut pas être écrasée ou modifiée par le script ou par l'action du bot. Si vous devez la modifier, vous devez mettre à jour la valeur sur la page Variable du script. Les variables secrètes ne peuvent pas être rendues modifiables.

Vous pouvez définir une valeur par défaut pour les variables de type Texte, Nombre et Sélection. Si la variable est modifiable, la valeur par défaut peut être écrasée en sélectionnant ou en saisissant une valeur différente lorsque vous ajoutez l'action à une réponse du bot. Si la variable n'est pas modifiable mais qu'elle est référencée dans le script d'une action, la valeur par défaut est utilisée, si elle en a une. Si aucune valeur par défaut n'est attribuée, la variable n'a pas de valeur dans le script.

Les variables que vous créez sont ajoutées à l'objetVariables dans l'intégration du script.

Objets standards et fonctions

En complément des fonctionnalités standard de JavaScript, Bot Builder dispose du framework suivant propre au robot :

  • L’objet Bot offre une solution différente pour déterminer comment votre robot interagit au cours des conversations.
  • L’objet Store permet de préserver les informations de contexte au cours d’une exécution de robot.
  • L'objet Variables contient toutes les variables que vous ajoutez à l'intégration du script.
  • La fonction fetch est une implémentation de la fonction fetch standard de JavaScript.
  • La console permet de procéder au débogage.

Dans la mesure où les scripts Bot Builder fonctionnent sur le serveur, certaines limitations sont à prendre en compte lors de la rédaction des scripts.

Objet Bot

L’objet Bot contient des méthodes qui déclenchent les actions du bot. Lors de l’écriture d’un script, l’éditeur Web indique toutes les méthodes disponibles, ce qui inclut leurs arguments et types. Les méthodes suivantes sont disponibles lorsque vous utilisez l’objet Bot :

De nombreuses méthodes de l'objet Bot peuvent être personnalisées avec un paramètre options . Options peut être fallbackText (repli) ou typing (saisie intelligente). Les valeurs possibles pour typing sont 1, 2 ou 3.

Options = {
	"fallbackText": "this is the fallback text",
	"typing": 2,
}

sendMessage

Saisissez le message en texte simple que le robot doit envoyer. Utilisez le format .sendMessage(text: string, options: Options): void. Le paramètreoptions n'est pas nécessaire.

Bot.sendMessage('This is message written by bot')
la sortie de l’exemple de méthode sendMessage

sendButtons

Procédez à la configuration et envoyez jusqu’à trois boutons. Tous les paramètres de bouton peuvent être organisés en définissant des attributs. Utilisez l’exemple suivant pour comparer les paramètres de bouton dans la boîte de dialogue avec les attributs du script. Utilisez le format .sendButtons(text: string, buttons: ButtonPayload[], options: Options): void. Le paramètreoptions n'est pas nécessaire.

Bot.sendButtons('This is message written by bot', [
{
	title: 'Button 1',
	intent: {
		name: 'mood'
	}
}
])
la sortie de l’exemple de méthode sendButtons

Vous pouvez également déclencher entityValue, text ou url depuis votre script.

La combinaison de ces attributs risque de créer une erreur ou un comportement inattendu.

// triggers intent
{
	title: 'Title',
	intent: 'mood'
}

// triggers intent with entity value
{
	title: 'Title',
	intent: {
		name: 'mood',
		entity: 'myEntity',
		value: 'entity value'
	}
}

// url
{
	title: 'Title',
	url: 'https://www.nice.com'
}

// text
{
	title: 'Title',
	text: 'This is a text'
}

sendQuickReplies

Configurez et envoyez jusqu’à trois réponses rapides. Tous les paramètres de réponse rapide peuvent être organisés en définissant des attributs. Les options relatives aux réponses rapides sont identiques aux options des boutons. Utilisez le format .sendQuickReplies(text: string, quickReplies: QuickReplyPayload[], options: Options): void. Le paramètreoptions n'est pas nécessaire.

Bot.sendQuickReplies('This is message written by bot', [
{
	title: 'Quick reply 1',
	intent: {
		name: 'mood'
	}
}
])

Vous pouvez également déclencher entityValue, text ou url depuis votre script.

La combinaison de ces attributs risque de créer une erreur ou un comportement inattendu.

// triggers intent
{
	title: 'Title',
	intent: 'mood'
}

// triggers intent with entity value
{
	title: 'Title',
	intent: {
		name: 'mood',
		entity: 'myEntity',
		value: 'entity value'
	}
}

// url
{
	title: 'Title',
	url: 'https://www.nice.com'
}

// text
{
	title: 'Title',
	text: 'This is a text'
}

sendCards

Configurez et envoyez jusqu’à 10 cartes. Utilisez le format .sendCards(cards: CardPayload[], options: Options): void. Le paramètreoptions n'est pas nécessaire.

Bot.sendCards([{
	title: 'Card title',
	description: 'Card description',
	image: 'https://picsum.photos/200/300',
	mimetype: 'image/jpeg',
	button: {
		title: 'Button title',
		url: 'https://www.nice.com/'
	}
}])
la sortie de l’exemple de méthode sendCards

sendMultimedia

Les entrées multimédias ne sont pas validées par Bot Builder, mais peuvent être validées dans d’autres intégrations. Le contenu de l’URL doit être disponible pendant toute la durée d’utilisation du script. Il doit être accessible de façon publique, car il sera téléchargé de nombreuses fois au cours de l’exécution du script. Le type de média et les restrictions de taille sont identiques lorsque vous utilisez une action de robot multimédia. Utilisez le format .sendMultimedia(url: string, mimetype: string, options: Options): void. Le paramètreoptions n'est pas nécessaire.

Bot.sendMultimedia('https://picsum.photos/200/300', 'image/jpeg')
la sortie de l’exemple de méthode sendMultimedia

sendRichLink

Configurez et envoyez un lien enrichi. Utilisez le format .sendRichLink(richlink: RichLinkPayload): void.

Bot.sendRichLink({
	title: 'Title',
	url: 'https://www.nice.com',
	image: 'https://picsum.photos/200/300',
	mimetype: 'image/jpeg'
})
la sortie de l’exemple de méthode sendRichLink

sendListPicker

Configurez et envoyez jusqu’à 12 options de sélection de liste. Toutes les options de sélection de liste peuvent être organisées en définissant des attributs. Les options des sélecteurs de liste sont identiques aux options pour les boutons. Utilisez le format .sendListPicker(message: string, description: string, actions: ListPickerPayload[], options: Options): void. Le paramètreoptions n'est pas nécessaire.

Bot.sendListPicker('Message', 'Description', [{
	title: 'Title',
	description: 'Description',
	image: {
		url: 'https://picsum.photos/200/300',
		mimetype: 'image/jpeg'
	}
	intent: {
		name: 'mood'
	}
}])
la sortie de l’exemple de méthode sendListPicker

handover

Configurez l’emplacement où handoverFermé Tout message de contact qui devrait déclencher le transfert vers un agent en direct doit être placé en utilisant un queueId. Celui-ci peut avoir la valeur null pour utiliser le réacheminement automatique, ou il peut s’agir de l'ID d’une file d'attente existante. Utilisez le format .handover(queueId: ?string): void.

Pour localiser un queueId :

  1. Dans CXone, cliquez sur le sélecteur d'application et sélectionnezACD.

  2. Allez à Digital Experience > Files d'attente de routage.

  3. Recherchez la file d’attente pour laquelle vous avez besoin d’un identifiant et cliquez sur Modifier.

  4. Sur la page de modification de la file d'attente, recherchez l’URL dans votre navigateur. Le nombre situé après /edit/ indique l’queueId. Il comporte normalement cinq chiffres et lettres divisés par des barres obliques. Par exemple, 67bf5865-4556-40db-ba44-6c0cc3f88ffa.

Bot.handover(null)
// or
Bot.handover('queueId')
la sortie de l’exemple de méthode handover

addTags

Configurez les balises à appliquer. Toutes les balises utilisées dans le script doivent déjà exister dans Bot Builder. Si l’une des balises appelées par le script n’existe pas, l’action sera ignorée. Utilisez le format .addTags(tags: string[]): void.

Bot.addTags(['Tag 1', 'Tag 2'])
la sortie de l’exemple de méthode addTags

waitForResponse

Dans certains cas, vous devez attendre une réponse personnalisée et poursuivre l’exécution du script. Dans la mesure où la communication avec le client est asynchrone, l’attente de la réponse est également asynchrone. La méthode Bot.waitForResponse prend un paramètre : le nom de la fonction qui sera exécutée une fois la réponse reçue. Utilisez le format .waitForResponse(functionName: string): void.

Le comportement de cette fonction est reporté. Cela signifie que le résultat ne prend pas effet immédiatement lors de son exécution. Au lieu de cela, une exécution de script en cours doit se terminer au préalable. Si vous voulez que le script se termine avec la fonction de comportement reporté, vous devez arrêter explicitement l’exécution du script en utilisant une déclaration ou des conditions de retour (return).

function main() {
	console.log('Testing wait for response')
	Bot.waitForResponse('response') //The script continues to run and the next line executes while listening for a customer response
	console.log('This is still going to be executed')
}

function response() {
	console.log('Customer responded', Bot.slots['last customer message'].value)
}

fillSlot

Configurez l’emplacementFermé Entité extraite du message du contact et enregistrée pour être utilisée dans les réponses du bot. Similaire à une variable. (slot) à appliquer. Tous les emplacements utilisés dans le script doivent déjà exister dans Bot Builder. Si l’un des emplacements appelés par le script n’existe pas, l’action sera ignorée.

Si vous souhaitez simplement stocker la valeur d’exécution du script, utilisez une variable locale ou utilisez l’objet Store. Utilisez le format .fillSlot(name: string, value: any[]): void.

Pour accéder à la valeur réelle de l’emplacement, vous devez accéder à l’attribut .value.

function main() {
	Bot.fillSlot('slotName', 'slotValue');
	console.log(Bot.slots.slotName.value);
}
la sortie de l’exemple de méthode fillSlot

slots

Dans la notation par point, l’éditeur peut indiquer les emplacementsFermé Entité extraite du message du contact et enregistrée pour être utilisée dans les réponses du bot. Similaire à une variable. (slots) disponibles, mais s’applique uniquement lorsque les noms d’emplacement ne contiennent pas d’espaces ou de caractères spéciaux. Lorsque les noms d’emplacement incluent des espaces ou des caractères spéciaux, il faut passer à la notation par crochets.

console.log(Bot.slots)

// example
let contactId = Bot.slots['contact.id'].value
let lastCustomerMessage = Bot.slots['last customer message'].value
la sortie de l’exemple de méthode slots

sendAsCustomer

Cette fonction vous permet d’ajouter ce que le contactFermé La personne interagissant avec un agent, un serveur vocal interactif (IVR), ou robot dans votre centre de contact. peut dire dans vos histoiresFermé Utilisé pour former le bot à la gestion des interactions en fonction de l'intention et du contexte et règlesFermé Utilisé pour définir la réponse du bot aux messages qui ne changent pas avec le contexte.. Utilisez le format .sendAsCustomer(text: string): void.

Le comportement de cette fonction est reporté. Cela signifie que le résultat ne prend pas effet immédiatement lors de son exécution. Au lieu de cela, une exécution de script en cours doit se terminer au préalable. Si vous voulez que le script se termine avec la fonction de comportement reporté, vous devez arrêter explicitement l’exécution du script en utilisant une déclaration ou des conditions de retour (return).

Bot.sendAsCustomer('Hello bot')

Objet Store

L’objet Store est créé pour des données pendant l’exécution du script. Par comparaison à une variable locale, il a l’avantage de pouvoir être utilisé par plusieurs fonctions .waitForResponse.

set, get

Store.set(name: string, value: any[]): void

Store.get(name: string): any[] 

function main() {
	Store.set('token', 'my-secret-token')
	Bot.waitForResponse('response')
}

async function response() {
	console.log(Store.get('token')) // my-secret-token is logged
}

Objet Variables

L'objet Variables contient les variables que vous créez dans l'intégration du script. Chaque variable est une propriété de Variables. Chaque variable possède un ensemble de sous-propriétés qui contiennent des informations à son sujet. L'exemple suivant montre une variable Sélection appelée colorChoice :

"colorChoice": {
  "defaultValue": "red",
  "options": [
	"red",
	"green",
	"blue"
	],
  "type": "select",
  "value": "red",
  "name": "colorChoice"
}

Dans l'exemple, la liste des valeurs affectées à la variable est contenue dans la propriété options .

Les propriétés defaultValue et value contiennent initialement la même valeur. Si vous ne spécifiez pas de valeur par défaut pour une variable de sélection, la valeur par défaut est null. Les valeurs des variables ne peuvent pas être modifiées dans le script, mais elles peuvent être rendues modifiables, puis modifiées lorsque l'action est utilisée dans une histoire ou une règle.

Références aux variables d'un script

Vous pouvez faire référence à la valeur d'une variable en utilisant la notation par points : Variables.varName.value

Référence à la liste des options d'une variable Sélection : Variables.varName.options

Affichage des variables existantes d'une intégration de scripts

Vous pouvez voir une liste des variables existantes et de leurs propriétés dans le script en ajoutant la ligne suivante à votre code, puis en exécutant le script. La liste s’affiche dans la console. Le code est le suivant : console.log(Variables). De même, vous pouvez afficher le contenu d'une seule variable en ajoutant console.log(Variables.varName.value) ou console.log(Variables.varName.options)à votre script.

Les fonctions fetch

fetch(url: string, ?options), où les options possibles sont :

  • method - 'GET', 'POST', 'PUT', 'DELETE'
  • headers
  • form_params
  • json
  • body

Utilisez fetch pour communiquer avec les API. Il peut s’agir de l’une des API CXone ou de votre propre API.

const URL = 'https://nice.com'

async function main() {
	// 1. using async/await
	try {
		const response1 = await fetch(URL, { 'method': 'GET' })

		console.log(
			'response 1',
			response1.ok,
			response1.status,
			response1.statusText,
			response1.url,
			response1.headers
		)
		console.log('response 1', await response1.text())
	} catch (exception) {
		console.log('Error occured', exception)
	}

	// 2. using Promises
	fetch(URL, { 'method': 'GET' })
		.then(response => {
			console.log(
				'response 2',
				response.ok,
				response.status,
				response.statusText,
				response.url,
				response.headers
			)
	
			return response.text()
		})
		.then(response => {
			console.log('response 2', response)
		})
		.catch(exception => {
			console.log('Error occured', exception)
		})
	
	// 3. using fetchSync
	try {
		const response3 = fetchSync(URL, { 'method': 'GET' })
		console.log('response 3', response3)
	} catch (exception) {
		console.log('Error occured', exception)
	}
}

fetchSync

La fonction fetchest une implémentation standard de la fonction fetch de JavaScript, qui renvoie Promise et implémente également les fonctions .json() ou .text() lors de la réponse.

Il existe également une variante synchrone fetchSync, qui renvoie la réponse directement, et non pas la promesse. Si vous souhaitez préserver le contexte asynchrone de JavaScript, utilisez une fonction fetch standard.

Fonction console

La fonction console sert à tester votre script. Vous pouvez consigner les données que vous voulez. Le résultat du journal est également stocké dans l’historique de conversation, mais n’est pas envoyé au contactFermé La personne interagissant avec un agent, un serveur vocal interactif (IVR), ou robot dans votre centre de contact..

la sortie de l’exemple de méthode log

log

Utilisez le format console.log(…output: any[]): void.

console.log('my log', 123, {pi: 3.14})

warn

Utilisez le format console.warn(…output: any[]): void.

console.warn('my warn', 123, {pi: 3.14})

info

Utilisez le format console.info(…output: any[]): void.

console.info('my info output', 123, {pi: 3.14})

debug

Utilisez le format console.debug(…output: any[]): void.

console.debug('my debug output', 123, {pi: 3.14})

error

Utilisez le format console.error(…output: any[]): void.

console.error('my error output', 123, {pi: 3.14})

Gestion des erreurs

onError

Vous pouvez gérer les erreurs résultant d’exceptions inattendues en définissant votre fonction onError.

let onError = (e) => console.log('my handler', e.message)
		
function main() {
	Bot.nonExistentMethod()
}

Limitations du script pour CXone Bot Builder

Les scripts personnalisés écrits dans Bot Builder fonctionnent sur le serveur. La section suivante précise les limitations actuelles qui garantissent des performances optimales aussi bien pour les scripts que le serveur :

  • Structure : tout le code doit être contenu dans la fonction main . Le code en dehors d'une fonction ne sera pas exécuté.
  • Limite maximale pour l’événement : chaque script est limité à un maximum de 200 événements par exécution de script. Les événements incluent toutes les fonctions et les actions déclenchées par chaque fonction.
  • Limite de mémoire : un maximum de 10 Mo de mémoire est alloué à chaque exécution de script.
  • Limite de temps d’exécution : l’exécution de chaque script est limitée à 10 secondes.
  • Limite d’appel pour les fonctions robot : les fonctions robot suivantes e peuvent être appelées que 20 fois par exécution de script :
    • sendMessage
    • sendButtons
    • sendQuickReplies
    • sendCards
    • sendMultimedia
    • sendRichLink
    • sendListPicker
    • handover
    • addTags
    • waitforResponse
  • Limite d’appel pour fillSlot : la fonction fillSlot ne peut pas être appelée plus de 100 fois par exécution de script.
  • Limite d’appel pour la fonction console  : les fonctions console suivantes ne peuvent être appelées que 100 fois par exécution de script :
    • log
    • info
    • warn
    • debug
    • error
  • Limite d’appel pour fetchSync : la méthode fetchSync ne peut pas être appelée plus de 20 fois par exécution de script.