Create a bot flow and use third-party ASR grammar quick start guide

1. Click Admin.
2. Under Integrations, click Integrations.
3. Click Integrations.
4. In the Search box, type Nuance Recognizer as a Service. The card for Nuance Recognizer as a Service appears.
5. Click Install.

To configure the Nuance Recognizer as a Service integration for one Nuance language group, perform the following steps:

1. Open the Nuance Recognizer as a Service integration:
   • If you did not previously installed the integration into your Genesys Cloud organization, install it now. 
   • If you installed the integration, open the Genesys Cloud Admin menu and under Integrations, click Integrations. Then, search for and open the Nuance Recognizer as a Service integration.
2. On the Nuance Recognizer as a Service integration page, click the Configuration tab.
3. Under Properties, locate the Recognizer Endpoint URL section.
4. In the Value field, enter the regional endpoint for the Nuance language group that your bot supports:
   • For example, if you want to use Nuance Recognizer as a Service for en-US, ja-JP, and zh-CN, use nr-apac4.api.nuance.com.
   • If your bot only supports one language, use the URI of a language group that includes the language and is closest to your organization’s location. For example, if your bot supports fr-FR by default and your organization exists in Switzerland, use nr-wu2.api.nuance.eu. For more information, see Language groups by region in the Nuance Recognizer documentation.
5. Click the Credentials tab. Genesys Cloud lists the credentials for all authorization endpoint URLs that you can use to authenticate to endpoints associated with the various Nuance language groups. Configure the credentials for the default recognizer endpoint only.
   Note: To determine what credentials to configure for a specific language group, check what Nuance region the language group belongs to based on its corresponding endpoint URL. For more information, see Geographies in the Nuance Mix documentation.
   Click the image to enlarge.
6. Click Configure for the Nuance Recognizer Credentials for the Default Recognizer Endpoint URL. The Configure Credentials dialog box opens.
7. Copy the “client_id” value from your OAuth configuration into the Nuance Client ID field. Use your AU, EU, or US client ID depending on whether your bot uses languages from the AU, EU, or US Nuance region.
   Note: For example, if the regional endpoint URI you specified in step 4 ends in nuance.eu, use the client ID of your mix.nuance.eu credentials. If the URI ends in nuance.com, use the client ID of your mix.nuance.com credentials.
   Click the image to enlarge.
8. Copy the “client_secret” value from your OAuth configuration into the Nuance Client Secret field. Use your AU, EU, or US client secret depending on whether your bot uses languages from the AU, EU, or US Nuance region.
   1. Copy the “private_key_id” from the JSON file into the Nuance Private Key ID field.
   2. Copy the “private_key” value from the JSON file into the Nuance Private Key field.
9. Click OK.
10. Click Save.
11. To activate the Nuance Recognizer as a Service status, in the Status column click Inactive. The Change Status dialog box opens.
12. Click Yes. The Nuance Recognizer as a Service integration status changes to Active.

1. Open the Nuance Recognizer as a Service integration:
   • If you did not previously installed the integration into your Genesys Cloud organization, install it now. 
   • If you installed the integration, open the Genesys Cloud Admin menu and under Integrations, click Integrations. Then, search for and open the Nuance Recognizer as a Service integration.
2. On the Nuance Recognizer as a Service integration page, click the Configuration tab.
3. Under Properties, locate the Recognizer Endpoint URL section.
4. In the Value field, enter a regional endpoint based on the following criteria:
   • If a language group includes all the languages that your bot supports, use its corresponding URI. For example, if you want to use Nuance Recognizer as a Service for en-US, ja-JP, and zh-CN, use nr-apac4.api.nuance.com. If your bot only supports one language, use the URI of a language group that includes the language and is closest to your organization’s location. For example, if your bot supports fr-FR by default and your organization is based in Switzerland, use nr-wu2.api.nuance.eu. For more information, see Language groups by region in the Nuance Recognizer documentation.
   • If the languages that your bot supports and you want to use Nuance Recognizer as a Service for belong to multiple language groups, use a URI of a language group that includes a language that your bot supports by default. Specify the URIs of the other language groups under the Advanced tab. For more information, see Language groups by region in the Nuance Recognizer documentation. 
5. Click the Advanced tab.
6. To configure mappings for the languages that Nuance does not serve through the default endpoint you previously specified in the Recognizer Endpoint URL section, follow these steps:
   Notes:

   • Except for the languages that the default regional endpoint covers, be sure to map all the languages to an appropriate Nuance endpoint.
   • If you map a language to a regional Nuance endpoint, then you must set the credentials for that language region under Credentials, even if the default regional endpoint and its corresponding credentials would cover that language.
   • If a language does not have a mapped value in the Advanced Configuration section, then Genesys Cloud attempts to use the default regional endpoint with the default credentials.
   1. (Optional) To download and inspect the JSON schema that Genesys Cloud validates your advanced configuration against, click Download Schema.
   2. Add a property named “endpointMappings” as an object.
   3. Add the language tags of your supported languages and the corresponding Nuance endpoints as key-value pairs to the object: You can copy and paste the following example into the Advanced Configuration editor and modify it according to your needs:

      {
      "endpointMappings": {
      "ca-ES": "nr-wu1.api.nuance.eu",
      "es-ES": "nr-wu1.api.nuance.eu",
      "es-US": "nr-na1.api.nuance.com",
      "gl-ES": "nr-wu1.api.nuance.eu",
      "va-ES": "nr-wu1.api.nuance.eu",
      "fr-FR": "nr-wu5.api.nuance.eu",
      "en-GB": "nr-wu1.api.nuance.eu",
      "eu-ES": "nr-wu1.api.nuance.eu"
      }
      }
      

      Note: The user interface validates the object against the expected JSON schema and informs you if the object does not comply.
7. Click the Credentials tab. Genesys Cloud lists the credentials for all authorization endpoint URLs that you can use to authenticate to endpoints associated with the various Nuance language groups.
   Note: To determine what credentials to configure for a specific language group, check what Nuance region the language group belongs to based on its corresponding endpoint URL. For more information, see Geographies in the Nuance Mix documentation.
   Click the image to enlarge.
   
8. Click Configure. The Configure Credentials dialog box opens.
9. Copy the “client_id” value from your OAuth configuration into the Nuance Client ID field. Use your AU, EU, or US client ID depending on whether your bot uses languages from the AU, EU, or US Nuance region.
   Note: For example, if the URI of the regional endpoint you want to configure credentials for ends in nuance.eu, use the client ID of your mix.nuance.eu credentials. If the URI ends in nuance.com, use the client ID of your mix.nuance.com credentials.
   Click the image to enlarge.
10. Copy the “client_secret” value from your OAuth configuration into the Nuance Client Secret field. Use your AU, EU, or US client secret depending on whether your bot uses languages from the AU, EU, or US Nuance region.
    1. Copy the “private_key_id” from the JSON file into the Nuance Private Key ID field.
    2. Copy the “private_key” value from the JSON file into the Nuance Private Key field.
11. Click OK.
12. Repeat step 8 for all other credentials that you must configure.
    Notes:

    • If you configured an endpoint mapping for a language in the Advanced tab, then you must configure the credentials for the specific Nuance authorization endpoint URL that the language’s group is associated with.
    • If you have not configured any endpoint mapping for the language in the Advanced tab, then you must configure the credentials for the default regional endpoint that you previously specified under the Properties tab.
13. Click Save.
14. To activate the Nuance Recognizer as a Service status, in the Status column click Inactive. The Change Status dialog box opens.
15. Click Yes. The Nuance Recognizer as a Service integration status changes to Active.

Install Nuance Recognizer as a Service

Click the image to enlarge.

Configure Nuance Recognizer as a Service

Click the image to enlarge.

• Nuance Recognizer as a Service overview
• Install Nuance Recognizer as a Service from the AppFoundry
• Configure Nuance ASR to use with Architect

<?xml version="1.0"?>
<grammar xmlns="http://www.w3.org/2001/06/grammar" xml:lang="en-US" version="1.0" root="fruits"> 
     <rule id="fruits" scope="public">
          <one-of>
               <item>apple</item>
               <item>banana</item>
               <item>blueberry</item>
               <item>cherry</item>
               <item>grape</item>
               <item>peach</item>
               <item>pear</item>
               <item>pineapple</item>
               <item>strawberry</item>
               <item>watermelon</item>
          </one-of>
     </rule>
</grammar>

1. Click Admin.
2. Under Architect, click Architect. Architect opens in a new tab.
3. Click Grammars.
4. Click Add. The Create New Grammar dialog box opens.
5. Name the grammar Fruit.
6. Under Grammar Description, add descriptive details about the grammar. For example, “list of fruit for sale.”
7. Click the Starting Language and select the initial language that you want the grammar to use.
8. Click Create. The Grammar Editor opens.
9. Depending on the type of grammar that you want to add, click one of the following tabs:
   • Voice 
   • DTMF
10. To manually add GRXML content from the Nuance Recognizer ASR grammar, enter the syntax into the editor.
    Note: If the grammar passes XML validation, then a green message appears, letting you know that the grammar is free of errors. If a red message appears, then Architect lets you know the location in the GRXML that the error or errors exist.
11. To upload a grammar file with the .gram extension, follow these steps:
    Note: If you switch from the .grxml file type to the .gram file type, then Architect removes existing .grxml file.
    1. Click .grxml and select .gram.
    2. Click Select File. The Add A Grammar File dialog box opens.
    3. Click Select .gram file and upload the appropriate file.
    4. Click Add File. Architect uploads the file but does not check for errors.
12. Click Save.

Grammar Editor for DTMF

The example in this article uses DTMF grammar. For details and an example of voice grammar, see Add a grammar for a bot flow in Architect.

Click the image to enlarge.

• Add a grammar for a bot flow in Architect

1. Create a new bot flow:
   1. From the Architect home page, click or hover over the Flows menu and select Bot Flow.
   2. Click  Add. The Create Flow dialog box opens.
   3. In the Name field, enter a unique name for the flow.
   4. (Optional) In the Description field, add a short sentence or phrase to describe this flow.
   5. Click the Default Language list and select the flow’s default supported language.
   6. Click the Divisions list and select the division in which to place the flow.
   7. Click Create Flow. The flow’s configuration page opens.
2. Under Natural Language Understanding, click Intents.
3. Add the first intent:
   1. Click Add Intent.
   2. Name the intent Pay my outstanding bill.
   3. Click Add Utterance.
   4. On the Utterances page, add an utterance. For example, “payment.” 
   5. Click Add.
   6. Repeat steps a-e to add another utterance. Best practice recommends that you add five or more utterances. 
4. Add the second intent:
   1. Click Add Intent.
   2. Name the intent Fruit order.
   3. Click Add Utterance.
   4. On the Utterances page, add an utterance. For example, “place order.” 
   5. Click Add.
   6. Repeat steps a-e to add more utterances. Best practice recommends that you add five or more utterances. 
5. Add slots:
   1. Under the Natural Language Understanding menu, click Slots.
   2. Click Add Slot. the Add Slot dialog box opens.
   3. Name the slot PickFruit.
   4. Under Associated Slot Type, select New List.
   5. Click Engine and select the third-party ASR engine. In this example, select Nuance Recognizer as a Service.
   6. Click Grammar and select the grammar that you added in the Step 2 section above, Fruit.
   7. Click Save.
   8. Repeat steps a-g to add a slot for Payment and associate it with the builtin:amountOfMoney existing slot type.
   9. Repeat steps a-c to add a slot for CustomerAccountNumber and associate it with a New RegEx slot type.
6. Add a slot type for the fruit example:
   1. Under the Natural Language Understanding menu, click Slot Types.
   2. Click Add Slot Type. The Add Slot Type dialog box opens.
   3. Name the slot Pick Fruit Type and then click Save.
   4. Add various slot type values, such as strawberry, pineapple, pear, peach, grape, cherry, blueberry, banana, apple, and watermelon.
      Note: The Payment slot is already related to a built-in slot type.
7. Configure the RegEx slot type that you created for the CustomerAccountNumber slot. Specify regular expressions that can identify a valid account number.
8. Save your bot flow and continue with Step 4.

Intents

Click the image to enlarge.

Add a slot

Click the image to enlarge.

Slot list

Click the image to enlarge.

Slot types

Click the image to enlarge.

• Work with intents in a bot flow
• Use built-in slot types in a bot flow
• Use custom list slot types in a bot flow
• Use built-in slot types in a bot flow
• Use custom list slot types in a bot flow

1. Under Starting Bot, click Default Bot.
2. Under Toolbox, expand the Ask menu and add an Ask for Intent action below start in the task editor.
3. From the Ask menu add an Ask for Slot action below the Fruit order path and configure the action:
   1. Click the Slot list and select PickFruit.
   2. Click the Question, change the text to ask “What type of fruit would you like to order?“, and click Save. Notice that the Grammar for this action uses the slot’s grammar.
4. From the Ask menu add another Ask for Slot action below the Fruit order path and configure the action:
   1. Click the Slot list and select CustomerAccountNumber.
   2. Click the Question, change the text to ask “What is your account number?“, and click Save.
5. To verify whether the customer enters a valid account number, add a Decision action from the Logical menu below the actions in the Fruit order path and configure the action using a custom expression based on your needs.
6. From the Communicate menu add Communicate actions below the Decision action’s Yes and No paths to inform the customer whether the account number is valid or not.
7. Under Toolbox, expand the Transfer menu and add a Transfer to ACD action below the Pay my outstanding bill path. 
8. Add your preferred action below the Pay my bill’s failure path. For example, a Communicate action.
9. Save and publish your flow.

Click the image to enlarge.

• Task and state editor actions
• Ask for Intent action
• Ask for Slot action

1. From the Architect home page, click or hover over the Flows menu and select Inbound Call.
2. Click Add. The Create Flow dialog box opens.
3. In the Name field, type a unique name for the inbound call flow. 
4. (Optional) In the Description field, add a short sentence or phrase to describe this flow.
5. Click the Divisions list and select the division in which to place the flow.
6. Click Create Flow. The flow’s configuration page opens.
7. Under Reusable Tasks, click  Tasks.
8. In the flow design area, click the task’s name and type a distinctive name for the task.
9. From the Toolbox, expand the Bot menu and add and configure a Call Bot Flow action below Start in the task editor:
   1. Under Bot Flow, search for and select the bot that you created in Section 3.
   2. Under Outputs, add an output variable for the Pickfruit slot that you configured in Section 3.
   3. Under Outputs, add another output variable for the CustomerAccountNumber slot that you configured in Section 3.
   4. Under Execution Results, add variables to store the Exit Reason and the Intent.
10. From the Toolbox, expand the Logical menu and add and configure a Decision action below the Call Bot Flow action:
    • To determine whether the invoked bot flow exited because the customer requested agent assistance, add the expression Task.ExitReason == "AgentRequestedByUser" in the Decision action’s Expression field.
11. Under the Decision action’s Yes path, add and configure a Transfer to ACD action. From the Toolbox, expand the Transfer menu and drag a Transfer to ACD action into the task editor:
    • Under Queue, select a queue to which to transfer the interaction.
12. Under the Decision action’s No path, add and configure another Decision action to configure actions based on the intent that the bot flow returned:
    • To determine whether Architect detected the intent to place an order, add the expression Task.Intent == "Fruit order" in the Decision action’s Expression field.
13. Under the From the Toolbox, expand the Transfer menu and drag a Transfer to Secure flow action into the task editor:
    1. Under Secure Call Flow, select the secure call flow to which to transfer the interaction.
    2. Under Invocation Data,  add the variables you configured for the Pickfruit and CustomerAccountNumber slots to pass the information these variables contain to the secure flow that you want to use for the order. You can use the Append function to append the two strings together: Append(Task.FruitToOrder, ",", Task.CustomerAccountNumber)and then in the secure call flow, you can use the following to access them separately:

       Split(Flow.InvocationData, ",")[0] -> Fruit Type 
       Split(Flow.InvocationData, ",")[1] -> Account Number

       Note: You can add and configure a Call Data Action to do a lookup in the secure call flow based on the customer’s account number to determine who is doing the ordering.
14. On the Reusable Tasks design area, click and click Set this as the starting task. Notice that the reusable task moves up to become the Starting Task, and the Initial Greeting now appears in the Starting Task area. Also, the Main Menu moves to the bottom of the page to Reusable Menus. As the menu is not used, you can delete it.
15. Save and publish your flow.

Now you can test and implement a bot flow that uses your third-party ASR grammar in an Architect inbound call flow.

Click the image to enlarge.

• Call Bot Flow action
• Create a flow