Scripting Details for CXone 机器人生成器
With script integrations, you can write custom JavaScript to tell your bot 代替现场人工坐席处理客户交互的软件应用程序。 how to respond in conversations. This page describes the methods, objects, and functions supported by 机器人生成器.
Script Variables
You can create variables to use in 机器人生成器 scripts. Variables can store a value to be used elsewhere in the script. You can use the variables anywhere in any of the scripts in a script integration. They can only be used in the script integration where you create them.
机器人生成器 scripts support three types of variables:
- Text: Text variables hold simple string values. The value you define is the default. You can make text variables visible in the UI of the custom bot action so that a value can be defined for each action.
- Select: Use select variables when you want to have multiple possible values for the variable. You can assign one of the values as the default. You can make text variables editable in the UI of the custom bot action.
- Secret: Use secret variables to hold private data, such as tokens or API credentials. After entering the value, 机器人生成器 masks all but the first five characters with asterisks ( * ). The value is read-only and cannot be overwritten or changed by the script or via the bot action. If you need to change it, you must update the value on the Variable page in the script.
The variables you create are added to the Variables object.
Editable Variables in Custom Bot Actions
Editable variables are visible in the UI of a custom bot action created in script integration. You can define a value for the variable when you add the custom bot action to a bot response. If you don't want a variable to be visible in the bot action, the script uses the default value defined when you create the variable.
When a Select type variable is editable, you can choose one of the defined values in the when you add the bot action to a story, rule, or fallback. Select variables that aren't editable use the default value, if one is assigned. If no default is assigned, the variable has no value in the script. However, the only way to modify the list of value options is by editing the variable definition on the script integration page.
For Text type variables, you can add any string value to an editable variable when you add a custom bot action to a bot response. If the variable has a default value, it's overridden by the value input through the bot response.
Standard Objects and Functions
In addition to standard JavaScript functionalities, 机器人生成器 has the following bot-specific framework:
- The Bot object provides an alternative way to craft how your bot responds in conversations.
- The Store object lets you keep the context information for one script run.
- The fetch function is an implementation of the standard JavaScript fetch.
- The console allows for debugging.
Because 机器人生成器 scripts operate on the server, there are some limitations to consider while building your scripts.
Bot Object
The Bot object contains methods that trigger bot actions. When writing a script, the web editor prompts you with all available methods including their arguments and types. The following methods are available when using the Bot object:
- sendMessage
- sendButtons
- sendQuickReplies
- sendCards
- sendMultimedia
- sendRichLink
- sendListPicker
- handover
- addTags
- waitForResponse
- fillSlot
- slots
- sendAsCustomer
Many methods in the Bot object can be optionally customized with an options parameter. Options can be fallbackText (fallback) or typing (smart typing). Possible values for typing are 1, 2, or 3.
Options = {
"fallbackText": "this is the fallback text",
"typing": 2,
}
sendMessage
Enter a plain text message for the bot to send. Use the format .sendMessage(text: string, options: Options): void. The options parameter is not required.
Bot.sendMessage('This is message written by bot')
sendButtons
Configure and send up to three buttons. All button settings can be arranged by setting attributes. Use the example below to compare the button settings in the dialog with the attributes in the script. Use the format .sendButtons(text: string, buttons: ButtonPayload[], options: Options): void. The options parameter is not required.
Bot.sendButtons('This is message written by bot', [
{
title: 'Button 1',
intent: {
name: 'mood'
}
}
])
You can also trigger entityValue, text, or url through your script.
Combining these attributes can result in an error or unexpected behavior.
// 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
Configure and send up to three quick replies. All quick reply settings can be arranged by setting attributes. The options for quick replies are the same as the options for buttons. Use the format .sendQuickReplies(text: string, quickReplies: QuickReplyPayload[], options: Options): void. The options parameter is not required.
Bot.sendQuickReplies('This is message written by bot', [
{
title: 'Quick reply 1',
intent: {
name: 'mood'
}
}
])
You can also trigger entityValue, text, or url through your script.
Combining these attributes can result in an error or unexpected behavior.
// 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
Configure and send up to 10 cards. Use the format .sendCards(cards: CardPayload[], options: Options): void. The options parameter is not required.
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/'
}
}])
sendMultimedia
Multimedia is not validated by 机器人生成器, but can be validated in other integrations. The content on the url must be available for the entire time the script is used. It must also be publicly accessible, as it will be downloaded repeatedly when the script is run. The media type and size restrictions are the same as when you use a multimedia bot action. Use the format .sendMultimedia(url: string, mimetype: string, options: Options): void. The options parameter is not required.
Bot.sendMultimedia('https://picsum.photos/200/300', 'image/jpeg')
sendRichLink
Configure and send a rich link. Use the format .sendRichLink(richlink: RichLinkPayload): void.
Bot.sendRichLink({
title: 'Title',
url: 'https://www.nice.com',
image: 'https://picsum.photos/200/300',
mimetype: 'image/jpeg'
})
sendListPicker
Configure and send up to 12 list picker options. All list picker options can be arranged by setting attributes. The options for list picker are the same as the options for buttons. Use the format .sendListPicker(message: string, description: string, actions: ListPickerPayload[], options: Options): void. The options parameter is not required.
Bot.sendListPicker('Message', 'Description', [{
title: 'Title',
description: 'Description',
image: {
url: 'https://picsum.photos/200/300',
mimetype: 'image/jpeg'
}
intent: {
name: 'mood'
}
}])
handover
Configure where the handover 任何应触发转移到真人坐席的联系消息 goes by using a queueId. This can be left null to use auto re-route, or it can be the id of an existing queue. Use the format .handover(queueId: ?string): void.
To locate a queueId:
-
在 CXone 中单击应用程序选择器
并选择ACD.
-
Go to Digital Experience > Routing Queues.
-
Locate the queue you need the id for and click Edit.
-
On the edit page for the queue, look at the URL in your browser. The number after /edit/ is the queueId. It should look like five sets of numbers and letters divided by dashes. For example, 67bf5865-4556-40db-ba44-6c0cc3f88ffa.
Bot.handover(null)
// or
Bot.handover('queueId')
addTags
Configure which tags should be applied. Any tags used in the script must already exist in 机器人生成器. If a tag is called in the script but doesn't exist, the action will be ignored. Use the format .addTags(tags: string[]): void.
Bot.addTags(['Tag 1', 'Tag 2'])
waitForResponse
In some cases, you need to wait for a customer response and continue with your script execution. Since communication with customer is asynchronous, waiting for response is also asynchronous. The Bot.waitForResponse method takes one parameter: the name of the function that will be executed after a response is received. Use the format .waitForResponse(functionName: string): void.
This function has a postponed behavior.This means the outcome doesn't take effect immediately when executed.Instead, a current script execution must finish first.If you want the script to end with postponed behavior function, you must explicitly stop the script execution using a return statement or conditions.
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
Configure which slot 从联系人的消息中提取并保存以用于机器人响应的实体。类似于变量。 should be applied. Any slots used in the script must already exist in 机器人生成器. If a slot is called in the script but doesn't exist, the action will be ignored.
If you just want to store the value for script run, use a local variable or use the Store object. Use the format .fillSlot(name: string, value: any[]): void.
To access the actual slot value, you must access the .value attribute.
function main() {
Bot.fillSlot('slotName', 'slotValue');
console.log(Bot.slots.slotName.value);
}
slots
In the dot notation, the editor can prompt available slots 从联系人的消息中提取并保存以用于机器人响应的实体。类似于变量。, but this is only applicable when slot names do not contain spaces or special characters. In cases where slot names include spaces or special characters, the bracket notation must be used instead.
console.log(Bot.slots)
// example
let contactId = Bot.slots['contact.id'].value
let lastCustomerMessage = Bot.slots['last customer message'].value
sendAsCustomer
This function allows you to add what the contact 与联络中心的坐席、IVR 或机器人交互的人员。 might say in your stories
用于训练机器人根据意图和上下文进行交互处理 and rules
用于定义机器人对不随上下文变化的消息的响应。. Use the format .sendAsCustomer(text: string): void.
This function has a postponed behavior.This means the outcome doesn't take effect immediately when executed.Instead, a current script execution must finish first.If you want the script to end with postponed behavior function, you must explicitly stop the script execution using a return statement or conditions.
Bot.sendAsCustomer('Hello bot')
Store Object
Store is an object created to store data during script execution. Compared to a local variable, it has the advantage that it can be used across multiple .waitForResponse functions.
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
}
fetch Functions
fetch(url: string, ?options), where possible options are:
- method - 'GET', 'POST', 'PUT', 'DELETE'
- headers
- form_params
- json
- body
Use fetch for communicating with APIs. These can be any of the CXone APIs or your own.
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
The fetch function is a standard implementation of JavaScript fetch, which returns Promise and also implements .json() or .text() functions on response.
There is also a synchronous variant fetchSync, which returns the response directly, not the Promise. If you want to stay consistent with the asynchronous world of JavaScript, use a standard fetch function.
Console Function
Console is used for testing your script. You can log any data. The result of the log is also stored in the conversation history but is not sent to the contact 与联络中心的坐席、IVR 或机器人交互的人员。.
log
Use the format console.log(…output: any[]): void.
console.log('my log', 123, {pi: 3.14})
warn
Use the format console.warn(…output: any[]): void.
console.warn('my warn', 123, {pi: 3.14})
info
Use the format console.info(…output: any[]): void.
console.info('my info output', 123, {pi: 3.14})
debug
Use the format console.debug(…output: any[]): void.
console.debug('my debug output', 123, {pi: 3.14})
error
Use the format console.error(…output: any[]): void.
console.error('my error output', 123, {pi: 3.14})
Error Handling
onError
You can handle errors from unexpected exceptions by defining your onError function.
let onError = (e) => console.log('my handler', e.message)
function main() {
Bot.nonExistentMethod()
}