4 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 Guidelines

An important part of configuring any skill is coming up with a good invocation name, which 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).

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

As the digital assistant essentially functions as a master bot, it comes with 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 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 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).

Add Utterances

The built-in intents come with some default example utterances. If you think those utterances don’t reflect the range of phrases that users might use for those intents, you can add more utterances.

  1. Click icon to open the side menu to open the side menu, select Development > Digital Assistants, and open your digital assistant.

  2. In the left navigation for the digital assistant, click This is an image of the Intent icon.

  3. Select the intent for which you want to add an utterance.

  4. In the Examples text field, type the utterance and press Enter.

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:

  1. Click icon to open the side menu to open the side menu, select Development > Digital Assistants, and open your digital assistant.

  2. In the left navigation for the digital assistant, click the Settings icon and select the Configurations tab.

  3. Scroll down to the Conversation Parameters section of the page.

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:



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:



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.

    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.
  • 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.

To access these settings:

  1. Click icon to open the side menu to open the side menu, select Development > Digital Assistants, and open your digital assistant.

  2. In the left navigation for the digital assistant, click icon for Settings and select the Configurations tab.

  3. Scroll down to the Conversation Parameters section of the page.

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:

  1. Click icon to open the side menu to open the side menu, select Development > Digital Assistants, and open your digital assistant.

  2. In the left navigation for the digital assistant, click icon for Settings and select the Configuration tab.

  3. For the Skill Name For Processing Message With Image Only parameter, enter name of the skill that will use this flow.

  4. 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:

  1. Click icon to open the side menu to open the side menu, select Development > Digital Assistants, and select your digital assistant.
  2. In the digital assistant's left navigation, click Skills icon.
  3. Select one of the skills that uses the parameter.
  4. 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.

Languages and Digital Assistants

Each digital assistant can function in one language, meaning that it can only understand input and do proper routing between skills if the input is in that language.

You can create digital assistants that communicate with users in:

  • English.

    Such digital assistants communicate with users in English (for example, when welcoming the user and prompting for disambiguation), even if the skills that they contain are designed to work in other languages.

  • Another language of your choosing.

    In this case, each skill that you add to the digital assistant must be configured to work in the same target language.

Though you can't create multi-language digital assistants, you can create multi-language skills and expose them individually in a channel.

Non-English Digital Assistants

If the audience for your digital assistant isn't primarily English-speaking, you can create a digital assistant for another single language.

Configure a Digital Assistant for a Non-English Language
  1. If you haven't done so already, configure a translation service for your Digital Assistant instance by:
    1. Clicking icon to open the side menu to open the side menu and selecting Settings > Translation Service.
    2. Clicking + Service.
    3. Entering the URL and Authorization token for the Microsoft Translator service or the Google Translation API in the Translation Services dialog.
    Refer to the documentation for Microsoft Translator and Google Translation API to find out how to get the URL and access token.

    Important:

    To use the Google Translation API, you need to generate the API Key. You create this key from the GCP Console (APIs & services > Credentials). To find out more, see the Google Cloud Platform Documentation.
  2. Set the translation service in your digital assistant by:
    1. Clicking icon to open the side menu to open the side menu, selecting Development > Digital Assistants, and selecting your digital assistant.
    2. In the digital assistant's left navbar, clicking the Settings(an image of the left navbar's Settings icon) icon and selecting the General tab.
    3. Navigating to the Translation Service dropdown and selecting your translation service.
  3. In the digital assistant, change the example utterances for the digital assistant's system intents to use the target language:
    1. In the left navigation for the digital assistant, click This is an image of the Intent icon.
    2. Select an intent.
    3. In the Examples section of the page, hover over an example, click it's Edit icon, and replace the text with an equivalent phrase in the target language. Then do the same thing for the intent's other examples.
    4. Repeat the previous two sub-steps for each intent.
  4. Update all of the configuration messages and prompts to use the target language of the digital assistant, which you can access by clicking and selecting the Configuration tab.
  5. In the digital assistant, add skills that have your target language as the predominant language.

    Once you add your first skill, the digital assistant's predominant language will be set to that skill's predominant language (and you won't be able to add skills with other predominant languages).

    You can determine a skill's predominant language by opening the skill, selecting the Settings(an image of the left navbar's Settings icon) icon in the left navbar, selecting the General tab, and scrolling to the Predominant Language setting.

    If the skill has Q&A, its data source must be in the target language.

    See Non-English Single-Language Skills for info on creating such skills.

Explicit Invocation in Non-English Digital Assistants

In non-English digital assistants, explicit invocation is only recognized by the digital assistant when a user provides the invocation name as the first words in the input.

For example, in a Spanish version of a skill called Pizza Joe, the following would be recognized as an explicit invocation:

Pizza Joe ordenar pizza 

If the user includes the invocation name in the input, but somewhere after the beginning (e.g. ordenar pizza de Pizza joe), the phrase can still be evaluated, but it will not be given the extra weight that explicit invocations receive.

How Non-English Digital Assistants Work Behind the Scenes

If you create a non-English digital assistant, you may find it useful to understand how the digital assistant handles non-English input behind the scenes.

By the time a non-English skill is published and ready to be added to a digital assistant, it will already have had its training corpus translated to English in the background (when the skill was trained). The resulting training model for the skill is in English, but the original non-English utterances are also stored for use when trying to determine candidate skills.

For any skills that contain Q&A, translation of the questions to English is done in the background when the digital assistant that they have been added to is trained.

Similarly, utterances for the digital assistant's system intents are translated when the digital assistant is trained.

Here's how non-English digital assistants work at runtime:

  1. The language processing framework translates the input from the target language into English, which is the language of the training model.
  2. The digital assistant determines the response in English.
  3. The language processing framework translates the response from English back to the target language presents it to the user.

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:

  1. Click icon to open the side menu to open the side menu, select Development > Digital Assistants, and open your digital assistant.

  2. In the left navigation for the digital assistant, click icon for Settings and select the Configurations tab.

  3. 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.message.channelConversation.channelType=='twilio')?then('true','false')}