Personalize Your Digital Assistant

Once you have created a digital assistant and added skills to it, you can customize some of the aspects of the digital assistant, such as the invocation name of the digital assistant’s skills and the language in the digital assistant’s help and exit intents.

Invocation Name

An important part of configuring a digital assistant is coming up with good invocation names for each skill. The invocation name is used in explicit invocation of the skill.

Because the routing model gives additional weight to skills invoked explicitly, a good invocation name helps ensure that users are successful when trying to access that skill (and, conversely, do not access that skill accidentally).

A skill's invocation name is also presented to the user in messages and dialogs to help disambiguate intents, show help for the skill, and signal exiting of the skill. So you should take care to make the invocation name sound natural and user-friendly in those contexts.

Modify a Skill's Invocation Name

The invocation name for a skill is initially set in the Invocation field when you are adding the skill to the digital assistant. That field is pre-populated with the skill's display name.

If you later want to update the invocation name for a skill in a digital assistant, do the following:

In the left navigation for the digital assistant, click .
Select the skill.
Scroll down to the Interaction Model section of the page and modify the value of the Invocation field.

Invocation Name Guidelines

Invocation names must have the following characteristic:

Be unique for each skill within a digital assistant.

They should also have the following characteristics:

Have a clear relationship to their function.
Be easy to remember.
Be easy to pronounce.
Not consist of just one word, unless it’s a distinct brand name.
Not be phrases that occur frequently in everyday speech like “hello”, ”please”, “thanks”, and ”yes”.
Not include words and phrases that would be commonly used when invoking the skill, such as “go to”, “open”, and “tell me”.

Explicit Invocation Patterns

Digital assistants will try to detect explicit invocation within the user input patterns described in the table below. When deciding on a skill’s invocation name, try to imagine if that invocation name would naturally fit into one of these patterns.

Segment 1	Segment 2	Segment 3	Segment 4	Examples (here Pizza Skill is the invocation name)
Starting Phrase (such as “ask”, “tell”, “use”, and “go to”)	Invocation Name	Preposition, Conjunction, or Punctuation	User Intent	Go to Pizza Skill to track my orders
Starting phrase	Invocation name	User Intent	-	Ask Pizza Skill track my orders
Invocation name	User Intent	-	-	Pizza Skill to check my orders
Invocation Name	-	-	-	Pizza Skill
Starting Phrase	Invocation Name	-	-	Use Pizza Skill

System Intents for Digital Assistants

As the digital assistant essentially functions as a master bot, it comes with a set of built-in system intents that are used to identify when a user has general requests for the digital assistant itself (and not the skills that the digital assistant contains).

The digital assistant's system intents are:

exit, which applies when the user signals the desire to exit the current conversation or context in the digital assistant.
help, which applies when the user greets the digital assistant or asks for help or orientation. See Start, Welcome, and Help States for details on how the digital assistant routes help intents.
unresolvedIntent, which applies to user input that doesn't match well with the exit and help intents. It improves classification of the exit and help intents (so that particularly ambiguous utterances aren't attributed to those intents).

Specify States for a Digital Assistant's System Intents

When a digital assistant matches user input with the digital assistant's help, exit, and unresolvedIntent intents, it provides default behavior:

For the help intent, it displays a welcome message and then cards for each skill. Each card contains a label based on the invocation name and options derived from example utterances that you gave for the skill's interaction model when you added the skill to the digital assistant.
For the exit intent, it exits the current context (which can be a flow in a skill or the skill itself) and provides a message that it has done so.
For the unresolvedIntent intent, it offers a message indicating it didn't understand what the user was looking for and then displays the same cards that are displayed for the digital assistant's help intent.

If you'd like to customize the behavior of the digital assistant when these system intents are matched, you can do so by configuring the digital assistant to respond to those intent matches with calls to specific states in a skill that you have added to your digital assistant.

To specify the state for the digital assistant's help intent:

Click to open the side menu, select Development > Digital Assistants, and open your digital assistant.
In the left navigation for the digital assistant, click and select the Configurations tab.
Scroll down to the Skill State Mappings section of the page.
For the Digital Assistant Custom Help Skill property, select the skill that contains the state that you want to use.
For the Digital Assistant Custom Help State property, select the state that you want to use.

Note

If your digital assistant contains only one skill, setting the above properties will have no effect. To determine the help state in this case, the digital assistant will use the Help State setting for the skill (which you can find by opening the skill, clicking its

icon, and selecting the Digital Assistant tab). If the Help State setting isn't set, the digital assistant will provide default help behavior for the skill.

To specify a state for the digital assistant's exit intent:

Click to open the side menu, select Development > Digital Assistants, and open your digital assistant.
In the left navigation for the digital assistant, click and select the Configurations tab.
Scroll down to the Skill State Mappings section of the page.
For the Digital Assistant Custom Exit Skill property, select the skill that contains the state that you want to use.
For the Digital Assistant Custom Exit State property, select the state that you want to use.

To specify the state for the digital assistant's unresolvedIntent intent:

Click to open the side menu, select Development > Digital Assistants, and open your digital assistant.
In the left navigation for the digital assistant, click and select the Configurations tab.
Scroll down to the Skill State Mappings section of the page.
For the Digital Assistant Custom UnresolvedIntent Skill property, select the skill that contains the state that you want to use.
For the Digital Assistant Custom UnresolvedIntent State property, select the state that you want to use.

Note

If your digital assistant contains only one skill, setting the above properties will have no effect. The digital assistant will defer to the skill for handling of the unresolved intent.

Add Utterances

The built-in intents come with their own training data. If you need to optimize resolution to these intents, you can add example utterances.

Click to open the side menu, select Development > Digital Assistants, and open your digital assistant.
In the left navigation for the digital assistant, click
Select the intent for which you want to add an utterance.
In the Examples text field, type the utterance and press Enter.

Note

Starting with platform version 20.12, training utterances in all of the natively-supported languages are built in to the digital assistant's system intents behind the scenes.

Pre-Seeded Training Data in System Intents

The digital assistant system intents are based on pre-seeded training data so that you don't need to create utterances to make these intents work.

The exit and help intents each contain sub-categories of training data.

The training data for the exit intent is divided into the following sub-categories:

Exit: requests to exit or leave a skill.
Farewell: phrases like "bye" and "farewell".

The training data for the help intent is divided into the following sub-categories:

Menu: requests to display a menu.
Help: requests for help.
Greeting: phrases like "hi", "hello", and "greetings".

If you have designed separate intents to handle any of these sub-categories of user input, you can disable the training data for those sub-categories.

Disable Pre-Seeded Training Data

If you have created your own intents for the purposes of responding to user greetings, requests for help, showing menus, and requests to exit, you can disable the corresponding set of pre-seeded data in the help or exit intent so that the related user utterances don't resolve to that system intent.

Click to open the side menu, select Development > Digital Assistants, and open your digital assistant.
In the left navigation for the digital assistant, click
In the list of intents, select the help or exit intent.
Click Pre-seeded data options.
For the category of training data in the intent that you want to disable, slide the switch to the Off position.
Click Apply.

Note

For the help intent, you can simply slide the Enable Intent switch to the Off position to disable all of the sub-categories of pre-seeded training data for that intent.

Customize Messages and Prompts

The digital assistant has a set of standard messages and prompts to handle situations such as:

Welcoming the user.
Offering help.
Providing a choice between multiple intents when it’s uncertain what intent the user is seeking.
Managing the transition when the user breaks the expected flow in a conversation.

When this happens, the digital assistant helps to manage the transition to and from the original flow.

In addition, there are settings for things like the maximum number of options to display in the help and welcome screens.

To access these settings:

Click to open the side menu, select Development > Digital Assistants, and open your digital assistant.
In the left navigation for the digital assistant, click and select the Configurations tab.
Scroll down to the Conversation Parameters section of the page.

Note

For digital assistants based on platform version 21.04 and higher, resource bundle entries are created for textual properties by default. You can access and edit the resource bundle entries for these properties by clicking

to open the Resource Bundles page and selecting the Configuration tab.

System Variables for Digital Assistants

You'll notice that there are several variables that appear in the default values for some conversation parameters. Here is the list of those system variables and what they represent:

system.routingFromSkill: the invocation name of the current skill (that the digital assistant is prepared to route away from).
system.routingToSkill: the invocation name of the skill that the digital assistant is prepared to route to.
system.routingFromIntent: the conversation name of the current intent (that the digital assistant is prepared to route away from).
system.routingToIntent: the conversation name of the intent that the digital assistant is prepared to route away to.
system.channelType: the type of the current channel.

Note

Each of these variables is only available in the conversation parameters where it is included in the default values. If you don't see one of these variables in the default value of a given configuration parameter, you can't use it there.

Limit the Frequency of Prompts

In the course of a conversation, a digital assistant may prompt a user multiple times, asking them to click a button or input text for situations such as:

confirming the desire to interrupt the current flow to switch to a different flow
confirming the resuming of the previous flow
exiting the flow

For example, this screenshot shows a prompt to confirm that the user really wants to switch to a different skill:

Description of interruption-prompt.png follows

But you may prefer the digital assistant to instead provide a message that details the routing change and then immediately start the new flow, like this screenshot shows:

Description of interruption-message.png follows

Prompts are important for disambiguation. But you may prefer to use messages in cases where the confidence score for an intent reaches a certain threshold.

Use the following configuration properties to determine conditions for displaying a message instead of a prompt:

Interrupt Prompt Confidence Threshold: Determines the confidence threshold that must be met for the digital assistant to respond with a message instead of a prompt when the user enters something that is not relevant to the current flow. By default, this property is set to 1.01 (101%), which effectively means that it is set to always display a prompt.
When the confidence score reaches or exceeds the value of the Interrupt Prompt Confidence Threshold, a message based on the value of the Interrupt Message property is displayed.

When the confidence score does not reach the value of the Interrupt Prompt Confidence Threshold, a prompt based on the value of the Interrupt Prompt property is displayed.
Resume Response Type: Determines how the user should be notified when an interrupted flow is resumed. The valid values are prompt (which is the default) and message.
Exit Prompt Confidence Threshold: Determines the confidence threshold that must be met for the digital assistant to respond to an exit request with only the exit confirmation message. By default, it is set to 1.01 (101%), which effectively means that it is set to always display a prompt.

Tip:

If you do not want any message displayed at all when the Interrupt Prompt Confidence Threshold is reached, you can simply delete the contents of the Interrupt Message property. Similarly, if you do not want any prompt or message displayed upon resuming the flow, set the Resume Response Type property to message and leave the contents of the Resume Message property blank.

To access these settings:

Click to open the side menu, select Development > Digital Assistants, and open your digital assistant.
In the left navigation for the digital assistant, click and select the Configurations tab.
Scroll down to the Conversation Parameters section of the page.

Note

If you decide to make a skill hidden, these prompts and messages will automatically not appear for that skill. See Hidden Skills.

Disable a Skill

If you want to turn off a skill in a digital assistant without removing it, you can disable it. When you disable a skill, you exclude it from the digital assistant's training model. Any user input that would otherwise match well with the skill's training data will instead resolve elsewhere (likely the digital assistant's unresolvedIntent).

To disable a skill:

In the left navigation for the digital assistant, click .
Select the skill you want to disable.
Turn the skill's Enabled switch to the OFF position.

Hidden Skills

In some cases, you might have some skills in your digital assistant that are designed to handle interactions that are not central to the main purpose of the digital assistant. For example, you might have skills that:

Handle irrelevant input, such as attempts at humor.
Provide information about the digital assistant itself.

In these cases, you might want the skill to play more of a background role in the digital assistant, where it responds when needed but it is not identified in menus or in transition messages and prompts.

For example, if you have a skill called Anger Management that is designed to respond to impolite or abusive language gracefully, you probably don't want this skill to be presented to users by name in the welcome menu or in a transition message like "Do you want to go to Anger Management now?"

For hidden skills, the following apply:

The skill is not listed in the default help and welcome menus.
When transitioning to or from that skill, no transition dialogs or prompts appear.
The skill can't be invoked by the user through explicit invocation.

Hide a Skill

To hide a skill so that it functions in the digital assistant but is never explicitly referenced by name:

Click to open the side menu, select Development > Digital Assistants, and open your digital assistant.
In the left navigation for the digital assistant, click
In the list of intents, select the intent.
Slide the Exposed switch to the Off position.

Note

It is not possible to hide all of the skills in a digital assistant. At least one has to be left exposed.

Image-Initiated Flows

For each digital assistant, it is possible to designate one skill that is able to start a flow when the user uploads an image.

The conditions are:

The user is not currently in a flow.
The user input that is intended to trigger the flow must contain only images.

Here’s how to set it up:

Click to open the side menu, select Development > Digital Assistants, and open your digital assistant.
In the left navigation for the digital assistant, click and select the Configuration tab.
For the Skill Name For Processing Message With Image Only parameter, enter name of the skill that will use this flow.
For the Skill Start State For Processing Message With Image Only parameter, enter name of the state to route to once the image-initated flow begins.

Set Values for Custom Parameters

If any of the skills that have been added to your digital assistant have defined custom parameters and they are scoped to be shared by the whole digital assistant (in other words, they are prefixed with da.), you can set the value for those parameters in the digital assistant.

To set the value of a custom parameter:

Click to open the side menu, select Development > Digital Assistants, and select your digital assistant.
In the digital assistant's left navigation, click .
Select one of the skills that uses the parameter.
Scroll down to the Parameters section of the page and enter a value for the parameter.
The updated parameter value will be applied for all skills that use the parameter.

Auto-Numbering for Digital Assistants

You can set up a digital assistant to use auto-numbering, so that it prefixes buttons and list options with numbers. This is particularly useful for digital assistants that run on text-only channels. When users can’t use tap gestures, they can still trigger the button’s postback actions by entering a number.

To set up auto-numbering for a digital assistant:

Click to open the side menu, select Development > Digital Assistants, and open your digital assistant.
In the left navigation for the digital assistant, click and select the Configurations tab.
Scroll down to the Conversation Parameters section of the page and fill in a value for the Enable Auto Numbering on Postback Actions property.

This property accepts FreeMarker expressions, so you can turn the property on conditionally. For example, the following value turns auto-numbering on for Twilio channels:
```
${(system.channelType=='twilio')?then('true','false')}
```

Disable Selection of Old Actions in a Digital Assistant

Digital assistants have an Enable Clicking History Actions switch that determines whether the users are allowed to select actions that the digital assistant offers to them earlier in the conversation. For example, the user conversation might be offered a menu of Human Resources actions in one turn of the conversation, then enter an unrelated question, and then later try to select one of the Human Resources actions that were presented earlier. By default, this switch is turned on.

Note

When this switch is turned on, it overrides any handling that may have been set up in any of your skills for user selection of out-of-order actions. If any of your skills are set up to provide their own handling of out-of-order actions, you should set this switch to the OFF position.

To prevent users from being able to click old actions in a conversation:

Click to open the side menu, select Development > Digital Assistants, and open your digital assistant.
In the left navigation for the digital assistant, click and select the Configurations tab.
Scroll down to the Conversation Parameters section of the page and slide the Enable Clicking History Actions switch to the OFF position.

Oracle Cloud Infrastructure Documentation