Reference external grammars

In Mix.dialog, you can reference external speech and DTMF grammars in your project settings and in question and answer nodes. At runtime when the Dialog service sends a grammar reference to a client application, it adds the language code and the channel name to the name of the grammar to form a relative URL path, as described below. If you configure your project with a base URL for external grammars, the Dialog service will also add that to the path when sending a grammar reference to the client application.

External grammar paths

Mix supports uncompiled (.grxml) and precompiled (.gram) grammar file formats. Unless you have specified one or more base URLs for external grammars in your project configuration, grammar files must be placed in specific directories, relative to the client application, following this pattern:

basePath/language/grammars/channel/filename

Where:

  • basePath is the path where the client application expects to find all required language-specific material (audio files and grammars); for example, http://webserver:8080/myContent
  • language is a directory named after the appropriate short language code (for example, en-US, fr-CA)
  • The constant name grammars (this allows you to store audio files on the same server)
  • channel is the name of the channel with any non-alphanumeric characters stripped (for example, IVRVoiceVA, not IVR/Voice VA)
  • filename is the name of the external grammar file

By default, when the Dialog service sends the location of grammars to a client application, it assumes that the client application knows the base URL; therefore, it only provides a relative path. It also automatically appends the version query parameter, which refers to a specific Dialog build. (Mix generates a unique internal version number for each deployment.) For example:

  • For a speech grammar: /en-US/grammars/IVRVoiceVA/myGrammar.grxml?version=1.0_12345689
  • For a DTMF grammar: /en-US/grammars/IVRVoiceVA/myGrammar_dtmf.grxml?version=1.0_12345689

Base URLs for external grammars

You can specify base URLs for external grammars as part of your project’s configuration. If a base URL is specified, the Dialog service provides a complete path to the client application. For example, assuming the following base URL:

http://myfileserver:9000

The Dialog service will send these URLs:

  • For a speech grammar: http://myfileserver:9000/en-US/grammars/IVRVoiceVA/myGrammar.grxml?version=1.0_12345689
  • For a DTMF grammar: http://myfileserver:9000/en-US/grammars/IVRVoiceVA/myGrammar_dtmf.grxml?version=1.0_12345689

The External Resources tab lets you specify a default base URL for all external grammars in a project. You can also set environment-specific base URLs, as appropriate.

By default, the External Resources tab has the following tabs:

  • Default: This is where you define the default base URL.
  • Sandbox: This is where you define the base URL for the Sandbox environment.

If you have multiple environments (for example, QA, Production), a tab is available for each environment.

Order of precedence for base URL values

You can specify a base URL in the following locations:

  • In the Default tab, which sets a value by default.
  • In a specific environment tab (such as Sandbox), which sets a value for this environment. This value takes precedence over the default value set on the Default tab.
  • When you create an application configuration, which sets a value for the environment where you deploy this application configuration. This value takes precedence over all other values.

Specify base URLs

  1. In the Mix dashboard, select the Projects tab.
  2. Select the project.
  3. Click the External Resources tab.
  4. Under External grammars base URL, enter the base URL.
    For example, for the coffee app, this might be https://coffee.app.com:443.
  5. Click Add base URL.
  6. (Optional) To specify a different base URL for the Sandbox or any other environment:
    1. Click the tab for the environment.
      For example, click the Sandbox tab.
    2. Click the Edit icon .
    3. Enter the desired base URL.

Edit a base URL

  1. Select the Default tab or the tab for the desired environment.
  2. Click the Edit icon .
  3. Enter the new base URL.

Delete the default base URL

  1. Select the Default tab.
  2. Click the Delete icon .
  3. Click Delete.

Delete environment-specific base URLs

  1. Select the tab for the desired environment (for example, Sandbox).
  2. Click the Delete icon .