Table of Contents
The model crawlSettings Object
Appendix A: Example with 5 Elements
Appendix B: Example with an empty model
Overview
The JSON document format is used to describe a model interexchange format with Cyara. It provides a facility for model specification export and import. This document describes elements currently available in Cyara Platform 7.3. Note for further reading that the current platform version exports will contain a single module named “Main”.
Structure
The JSON document contains four main sections: common model info, modules, elements, and links. The graphical representation is not exported/imported as the model uses auto-layout.
The structure is designed to describe directed graphs; to do so, the JSON document uses a node and edge paradigm to have a complete description of the model.
Physical Document Structure
The diagram below defines a high-level physical JSON document structure:
Model: the CX Model
Modules: in 7.3, just a single module “Main” containing all elements
Elements: in 7.3, the start of the model and menus
Links - in 7.3, the sequence and input connectors
Logical Document Structure
To describe a directed graph, a tree structure is not enough, so model elements and links use identification references. Every module element has a unique identifier “id” which is used to build the logical structure.
Each module is a collection of element references. This allows for the creation of a structure where elements can be grouped together into separate modules. If required, it could also represent overlapping modules. As noted above, in the current version, a single module “Main” is supported.
The graph is described by the following elements:
Element describes a model node such as a menu.
Link has “source” and “target” attributes that link two elements together.
Below is a representation of the Element and Link inheritance:
The logical JSON structure for directed graph linking is as shown below:
On the left side, a sequence link joins the entry of the diagram with the main menu.
On the right side, several input links join a menu with submenus.
JSON Document Sections
The Root (Model) { } Object
The model section contains general information about the model such as its name and configuration defaults. The summary is followed by a diagram graph description with an array of elements and links between them.
In the below description, “Req” (required column) defines if the attribute must be passed in for the “Create” operation.
Parent
- None
Attributes
|
Name |
Type |
Req |
Default |
Description |
|
modelId |
string |
N |
|
Unique identifier of the model. |
|
schemaVersion |
string |
Y |
|
The version of the schema, matches REST API version (3.0). |
|
name |
string |
Y |
|
Name of the model. |
|
type |
string |
N |
IVR |
Model type, reserved for future use. Defaults to “IVR”. |
|
minPsst |
number |
N |
|
Minimum post speech silence timeout for the Crawl and Test Case generation functions. If the value is not provided, it will default to 1 second. The attribute is nullable - “null” can be passed as a valid value. |
|
entryModule |
string |
Y |
|
Reference to the main module defined as entry. In the current version of the CX Model, there can be only one module. |
|
dateCreated |
datetime |
N |
|
Date when the model was created. ISO 8601 format yyyy-MM-ddThh:mm:ssZ (e.g., 2014-01-01T12:00:00Z) |
|
lastModified |
datetime |
N |
|
Date when the model was updated. ISO 8601 format yyyy-MM-ddThh:mm:ssZ (e.g., 2014-01-01T12:00:00Z) |
|
modifiedBy |
string |
N |
|
Userid of the user who modified the model. |
|
language |
string |
Y |
|
Model language, for example, “en_US” |
|
|
object |
N |
|
A model Crawl function settings object which contains a transcriberSpeaker object. |
|
object |
N |
|
Model Test Case quality criteria definition stored in a testDefaults object. If the criteria is not specified, the account default values are used instead. |
|
|
array |
Y |
|
A collection of modules. The model will always have at least one module referenced by model “entryModule” attribute. In the current version only one module is supported. Reserved for future use to separate model in multiple modules. |
|
|
array |
Y |
|
A collection of elements. Elements are grouped into modules. In the current version, all elements are contained within a single module. |
|
|
array |
Y |
|
A collection of links that connect two elements together. |
Example
Retrieve
{
"modelId": 1,
"schemaVersion": "3.0",
"name": "Simple IVR",
"type": "IVR",
"minPsst": 1,
"entryModule": "1",
"dateCreated": "2016-02-23T03:19:10.970Z",
"lastModified": "2016-02-23T03:19:22.700Z",
"modifiedBy": "john.smith",
"language": "en_US"
Create
{
"schemaVersion": "3.0",
"name": "Simple IVR",
"entryModule": "1",
"language": "en_US"
The model crawlSettings Object
The crawl settings object is a container for custom Crawl configuration.
Parent
Attributes
|
Name |
Type |
Req |
Default |
Description |
|
object |
N |
|
A definition of the transcription speaker to use for the model crawl function. If this object is not defined, the create function will use the /language attribute and pick the default one for the language specified. |
The transcriberSpeaker Object
The Transcriber speaker object under Crawl settings defines the transcriber configuration. It describes which engine/language/customization the Crawl function should use to convert “heard” audio into a prompt text.
Parent
Attributes
|
Name |
Type |
Req |
Default |
Description |
|
id |
integer |
N |
|
Unique identifier of the configured speaker. It can be specified if the “ID” is known. If the attribute is omitted, the name of the speaker will be used. |
|
name |
string |
Y |
|
Name of the transcription speaker. If the speaker is not found, then the model language will be used to pick an existing one. The speaker list can be found under CX Models > Speakers menu. |
Example
"transcriberSpeaker": {
"id": 23,
"name": "English (USA) Independent"
}
The testDefaults Object
Within the model definition, it is possible to override quality criteria specified in Cyara account default configuration. The quality criteria contains the default threshold for multi-pass speech recognition and perceptual evaluation of speech quality.
Parent
Attributes
|
Name |
Type |
Req |
Default |
Description |
|
mpsrLevel |
object |
N |
|
An object with MPSR quality defaults. |
|
pesqLevel |
object |
N |
|
An object with PESQ quality defaults Note: The testDefaults/pesqLevel object will not reference an audio file. |
Example
"testDefaults": {
"mpsrLevel": {
"minor": 80.0,
"major": 60.0
},
"pesqLevel": {
"referenceAudio": null,
"minor": 3.6,
"major": 3.2
}
}
The modules Array
A collection of module elements. Currently, the platform supports a single module. In future releases, support for multiple modules will be added. Module attributes are described below.
Parent
Attributes
|
Name |
Type |
Req |
Default |
Description |
|
id |
integer |
Y |
|
Unique identifier of the module. The main module id will be referenced by /entryModule attribute. |
|
name |
string |
Y |
|
Name of the module. |
|
entryElement |
string |
Y |
|
Entry element from the element collection. A start point where the module starts. For the main module, there will be one entry point defined with a IVR phone number specified. |
|
elementRefs |
array |
Y |
|
An array of string IDs referencing module elements. This defines a group of elements that make up a module. |
Example
"modules": [
{
"id": "1",
"name": "Main",
"entryElement": "E1",
"elementRefs": [ "0", "1", "2", "3" ]
}
]
The elements Array
A collection of model graph elements. The elements can have the following sub-types:
- Entry
- Menu
Parent
Attributes
The array can be composed of following objects:
- Entry: in the current version, a single entry element is supported
- Menu
The Entry Object
The “Entry” object defines the first element in the CX Model diagram. It stores the phone numbers to call and ANI/CLI to simulate.
Parent
Attributes
|
Name |
Type |
Req |
Default |
Description |
|
id |
string |
Y |
|
Unique identifier of the element. |
|
name |
string |
Y |
|
Name of the element. |
|
type |
string |
Y |
|
Type of the element. For entry, a constant “Entry” |
|
phoneNo |
string |
Y |
|
A phone number for the model. Usually references the IVR entry point. The number will be used by generated Test Cases or the Crawl function. |
|
callingPhoneNo |
string |
Y |
|
A phone number to present as the calling number (ANI/CLI). The number will be used by the generated Test Cases and the Crawl function. |
|
dateCreated |
datetime |
N |
|
Date when the element was created.
|
|
lastModified |
datetime |
N |
|
Date when the element was last modified. |
|
userAttributes |
array |
N |
|
An array of key-value pairs. The values can be used to upload additional element information. In the current release, this information will not be visible in the CX Model Editor; however, the data will be attached to the model export. |
Example
{
"id": "E1",
"name": "555221",
"type": "Entry",
"phoneNo": "555221",
"callingPhoneNo": "555212",
"dateCreated": "2016-02-23T03:19:10.970Z",
"lastModified": "2016-02-23T03:19:22.700Z",
"userAttributes": {
"department": "Sales"
}
}
The Menu Object
Parent
Attributes
|
Name |
Type |
Req |
Default |
Description |
|
id |
string |
Y |
|
Unique identifier of the element. |
|
name |
string |
Y |
|
Name of the element. |
|
type |
string |
Y |
|
Type of the element. For menu, a constant “Menu” |
|
object |
Y |
|
The content of the menu prompt. See prompt object for more details. |
|
|
note |
string |
N |
|
A free comment. |
|
minPsst |
number |
N |
|
Menu post silence timeout value. If specified, it will override the model value. |
|
language |
string |
N |
|
Menu language. If specified, it will override the model value. Format: <lang>_<country>. For example: “en_US” |
|
object |
N |
|
Defines menu crawling settings. See menu crawlSettings for more details. |
|
|
object |
N |
|
Defines quality criteria for the particular menu. See testSettings for more details. |
|
|
dateCreated |
datetime |
N |
|
Date when the menu was created. ISO 8601 format yyyy-MM-ddThh:mm:ssZ (eg. 2014-01-01T12:00:00Z) |
|
lastModified |
datetime |
N |
|
Date when the menu was updated. ISO 8601 format yyyy-MM-ddThh:mm:ssZ (eg. 2014-01-01T12:00:00Z) |
|
userAttributes |
array |
N |
|
An array of key-value pairs. The values can be used to upload additional element information. In the current release, this information will not be visible in the CX Model Editor; however, the data will be attached to the model export. |
Example
{
"id": "7",
"type": "Menu",
"prompt": {
"text": "Please wait to be connected to your stock broker.",
"userVerified": true,
"source": "User"
},
"note": null,
"minPsst": null,
"language": null,
"crawlSettings": {
"allow": null,
"transcriberSpeaker": null
},
"testSettings": {
"pause": {
"min": 0.0,
"max": 0.0
},
"threshold": {
"minor": 3.0,
"major": 5.0
},
"mpsrLevel": null,
"pesqLevel": {
"referenceAudio": {
"name": "Step-2.wav",
"folder": "\\BigBank\\"
},
"minor": 3.6,
"major": 3.2
}
},
"userAttributes": {
"department": "Sales"
}
"name": "Stocks",
"dateCreated": "2018-10-16T12:53:45.7331743Z",
"lastModified": "2018-10-23T11:22:55.8787599Z"
}
The prompt Object
The prompt object determines attributes for the Crawl function, such as allowing crawling beyond this point and which transcriber to use.
Parent
Attributes
|
Name |
Type |
Req |
Default |
Description |
|
text |
string |
Y |
|
The content of the menu prompt. |
|
userVerified |
boolean |
Y |
|
“true” if the prompt has been verified by a user. Any menu created by a Crawl has to be verified by a user. |
|
source |
string |
N |
User |
The prompt was created by:
|
Example
"prompt": {
"text": "Welcome to Big Bank, press 1 for internet banking service, press 2 for new accounts, press 3 for stocks and 4 for derivatives..",
"userVerified": true,
"source": "User"
}
The menu crawlSettings Object
The Crawl settings object determines attributes for the Crawl function, such as allowing crawling beyond a specific menu and which transcriber to use to convert audio prompts to text. If the object is not specified, the model will use the model default Crawl settings.
Parent
Attributes
|
Name |
Type |
Req |
Default |
Description |
|
allow |
string |
N |
Yes |
Specifies if the Crawler function is allowed to Crawl beyond this menu. Possible values:
|
|
object |
N |
|
If specified will override transcriber specified in the model. See transcriberSpeaker object for more details. |
Example
"crawlSettings": {
"allow": "NoOther",
"transcriberSpeaker": {
"id": 23,
"name": "English (USA) Independent"
}
The testSettings object
The test settings object describes how the particular menu can be verified. Several quality criteria attributes can be specified. The values will be used to generate Test Cases.
Parent
Attributes
|
Name |
Type |
Req |
Default |
Description |
|
object |
N |
|
Either pesqLevel or mpsrLevel object is allowed. pesqLevel requires a reference to the audio file library. The library can be found under Tools > Audio Files. See pesqLevel object for more details. |
|
|
object |
N |
|
Either pesqLevel or mpsrLevel object is allowed. See mpsrLevel object for more details. |
|
|
object |
N |
|
A threshold object to define minor/major wait time for a reply. See threshold object for more details. |
|
|
object |
N |
|
A pause object, how long to pause before the next prompt. See pause object for more details. |
Example
"testSettings": {
"pause": {
"min": 0.0,
"max": 0.0
},
"threshold": {
"minor": 3.0,
"major": 5.0
},
"mpsrLevel": null,
"pesqLevel": {
"referenceAudio": {
"name": "Step-2.wav",
"folder": "\\BigBank\\"
},
"minor": 3.6,
"major": 3.2
}
}
The links Array
A collection of links between model elements. The following sub-types of links are available:
- Sequence: link to transition between elements unconditionally
- Input: link to transition between elements on a specific user input, for example, DTMF entry
Parent
Attributes
The array can be composed of the following objects:
- SequenceLink: in the current version, sequence link is used to connect the entry element to the main menu
- InputLink
The SequenceLink Object
A basic link element that connects two elements without any additional information.
Parent
Attributes
|
Name |
Type |
Req |
Default |
Description |
|
id |
string |
Y |
|
Unique identifier of the link. |
|
source |
string |
Y |
|
Reference to an element from which to draw the link. |
|
target |
string |
Y |
|
Reference to an element to which to draw the link. |
|
type |
string |
Y |
|
Type of the link “Sequence” for the sequence link. |
Example
{
"id": "1",
"source": "E1",
"target": "1",
"type": "Sequence"
}
The InputLink Object
The input link element connects a parent menu element with another menu element. Each link has additional attributes with user input that make the transition. The user input could be DTMF tones or voice commands.
Parent
Attributes
|
Name |
Type |
Req |
Default |
Description |
|
id |
string |
Y |
|
Unique identifier of the link. |
|
source |
string |
Y |
|
Reference to a menu element from which to draw the link. |
|
target |
string |
Y |
|
Reference to an element to which to draw the link. |
|
type |
string |
Y |
|
Type of the link “Sequence” for the sequence link. |
|
input |
object |
Y |
|
Input entered in the “source” menu to invoke a transition to the “target” element. |
The input Object
The input describes user input that makes an “InputLink” transition to occur. An input could be DTMF tone or a voice command.
Parent
Attributes
|
Name |
Type |
Req |
Default |
Description |
|
type |
string |
Y |
|
Input can be of the following type:
|
|
value |
string |
N |
|
A DTMF or Speech input to invoke transition from. If the input type is “NoInput, the value attribute can be omitted. |
Example
{
"id": "5",
"type": "Input",
"input": {
"type": "Speech",
"value": "Help"
},
"source": "4",
"target": "24"
}
The mpsrLevel Object
The MPSR level object describes minor and major thresholds of the multi pass speech recognition score. The score ranges from 0 to 100 where 0 is “no match” and 100 a “perfect match”.
Parent
Attributes
|
Name |
Type |
Req |
Default |
Description |
|
minor |
number |
Y |
|
A threshold between “Failed” and “Satisfactory” MPSR score. Can be a number from 0 to 100 with one decimal place. For example 65.5. The value must be less than the major level attribute. |
|
major |
number |
Y |
|
A threshold between “Satisfactory” and “Success” MPSR score. Can be a number from 0 to 100 with one decimal place. For example, 80.5. The value must be greater than the minor level attribute. |
Example
"mpsrLevel": {
"minor": 80.0,
"major": 60.0
}
The pesqLevel Object
The PESQ level object describes minor and major thresholds of perceptual evaluation of speech quality score. The score ranges from 0 to 5, where 1 is “bad” and 5 “excellent”. The quality is evaluated against a reference audio from the Cyara Platform Audio Library.
Parent
Attributes
|
Name |
Type |
Req |
Default |
Description |
|
referenceAudio |
object |
Y* |
|
(*) Not required when used to describe /testDefaults Required when it is used to describe menu element test settings. See referenceAudio object definition. The library can be located under Tools > Audio Files. |
|
minor |
number |
Y |
|
A threshold between “Failed” and “Satisfactory” PESQ score. Can be a number from 1 to 5 with one decimal place. The value must be less than the major level attribute. |
|
major |
number |
Y |
|
A threshold between “Satisfactory” and “Success” PESQ score. Can be a number from 1 to 5 with one decimal place. For example, 4.5. The value must be greater than the minor level attribute. |
Example
"pesqLevel": {
"referenceAudio": {
"name": "Step-2.wav",
"folder": "BigBank\\"
},
"minor": 3.6,
"major": 3.2
}
referenceAudio object
The referenceAudio object points to a file in the platform Audio File library. It is used as a part of the PESQ score level specification.
Parent
Attributes
|
Name |
Type |
Req |
Default |
Description |
|
name |
string |
Y |
|
Name of the file in the library. The library can be located under Tools > Audio Files. For example: “WelcomeMessage.wav” |
|
folder |
string |
Y |
|
Subfolder within the library. The value for root is "\\". The value for folder “BigBank” is “BigBank\\” The value for “BigBank” subfolder “Support” is “BigBank\\Support\\” |
Example
"referenceAudio": {
"name": "Step-2.wav",
"folder": "BigBank\\"
}
The threshold Object
Response time threshold for a menu prompt. The value can be specified in seconds from 0 to 3600.
Note: Compared to other quality criteria, the minor threshold will be larger than the major. The longer we have to wait for a prompt, the worse the menu performance.
Parent
Attributes
|
Name |
Type |
Req |
Default |
Description |
|
minor |
number |
Y |
|
A threshold between a “Failed” and a “Satisfactory” response time. Can be a value in seconds from 0 to 3600 with two decimal places. The value must be greater than the major level attribute. |
|
major |
number |
Y |
|
A threshold between a “Satisfactory” and a “Success” PESQ score. Can be a value in seconds from 0 to 3600 with two decimal places. For example, 20.25. The value must be less than the minor level attribute. |
Example
"threshold": {
"minor": 3.0,
"major": 5.0
}
The pause Object
Pause specifies a pause to take before the platform should start listening for the prompt. Typically in most models, the default value is 0.
Parent
Attributes
|
Name |
Type |
Req |
Default |
Description |
|
min |
number |
Y |
|
Can be a value in seconds from 0 to 120 with two decimal places. The value must be less than the max attribute. |
|
max |
number |
Y |
|
Can be a value in seconds from 0 to 120 with two decimal places. The value must be greater than the min attribute. |
Example
"pause": {
"min": 0.0,
"max": 0.0
}
Appendix A: Example with 5 Elements
The example consists of 5 elements: entry, main menu, and 3 sub-menus.
- One of the elements accepts speech input
- You will notice many of the settings for elements are “null”; this means that the defaults configured in the model are active. The null elements can also be deleted; however, we chose to print them to be more verbose
{
"modelId": 3,
"schemaVersion": "3.0",
"name": "Big Bank IVR v1.0",
"type": "IVR",
"minPsst": null,
"entryModule": "1",
"dateCreated": "2018-10-16T12:53:45.3231481Z",
"lastModified": "2018-10-23T14:39:17.7931571Z",
"modifiedBy": "admin",
"language": "en-US",
"crawlSettings": {
"transcriberSpeaker": {
"id": 3,
"name": "English (USA) - Speaker Independent v1"
}
},
"testDefaults": {
"mpsrLevel": {
"minor": 80.0,
"major": 60.0
},
"pesqLevel": {
"referenceAudio": null,
"minor": 3.6,
"major": 3.2
}
},
"modules": [
{
"id": "1",
"name": "Main",
"entryElement": "E3",
"elementRefs": [
"E3",
"4",
"5",
"6",
"7"
]
}
],
"elements": [
{
"phoneNo": "55522141412",
"callingPhoneNo": "",
"type": "Entry",
"id": "E3",
"name": "55522141412",
"dateCreated": "2018-10-16T12:53:45.3231481Z",
"lastModified": "2018-10-23T14:39:17.7931571Z"
},
{
"prompt": {
"text": "Welcome to Big Bank, press 1 for internet banking service, press 2 for new accounts, press 3 for stocks and 4 for derivatives..",
"userVerified": true,
"source": "User"
},
"note": null,
"minPsst": null,
"language": null,
"crawlSettings": {
"allow": null,
"transcriberSpeaker": null
},
"testSettings": {
"pause": null,
"threshold": null,
"mpsrLevel": {
"minor": null,
"major": null
},
"pesqLevel": null
},
"userAttributes": null,
"type": "Menu",
"id": "4",
"name": "Welcome",
"dateCreated": "2018-10-16T12:53:45.7321738Z",
"lastModified": "2018-10-16T12:53:45.7321738Z"
},
{
"prompt": {
"text": "Welcome to Banking Services. Please enter your account number to authenticate.",
"userVerified": true,
"source": "User"
},
"note": null,
"minPsst": null,
"language": null,
"crawlSettings": {
"allow": null,
"transcriberSpeaker": null
},
"testSettings": {
"pause": null,
"threshold": null,
"mpsrLevel": {
"minor": null,
"major": null
},
"pesqLevel": null
},
"userAttributes": null,
"type": "Menu",
"id": "5",
"name": "Banking Services",
"dateCreated": "2018-10-16T12:53:45.7331743Z",
"lastModified": "2018-10-16T12:53:45.7331743Z"
},
{
"prompt": {
"text": "What kind of account you want to open? Please press 1 for checking, 2 for credit or 3 for savings.",
"userVerified": true,
"source": "User"
},
"note": null,
"minPsst": null,
"language": null,
"crawlSettings": {
"allow": null,
"transcriberSpeaker": null
},
"testSettings": {
"pause": null,
"threshold": null,
"mpsrLevel": {
"minor": null,
"major": null
},
"pesqLevel": null
},
"userAttributes": null,
"type": "Menu",
"id": "6",
"name": "New Accounts",
"dateCreated": "2018-10-16T12:53:45.7331743Z",
"lastModified": "2018-10-16T12:53:45.7331743Z"
},
{
"prompt": {
"text": "Please wait to be connected to your stock broker.",
"userVerified": true,
"source": "User"
},
"note": "A new version with speech input",
"minPsst": null,
"language": null,
"crawlSettings": {
"allow": "NoOther",
"transcriberSpeaker": null
},
"testSettings": {
"pause": {
"min": 0.0,
"max": 0.0
},
"threshold": {
"minor": 3.0,
"major": 5.0
},
"mpsrLevel": null,
"pesqLevel": {
"referenceAudio": {
"name": "Step-2.wav",
"folder": "BigBank\\"
},
"minor": 3.6,
"major": 3.2
}
},
"userAttributes": null,
"type": "Menu",
"id": "7",
"name": "Stocks",
"dateCreated": "2018-10-16T12:53:45.7331743Z",
"lastModified": "2018-10-23T14:39:17.7931571Z"
}
],
"links": [
{
"type": "Sequence",
"id": "1",
"source": "E3",
"target": "4"
},
{
"input": {
"type": "Dtmf",
"value": "1"
},
"type": "Input",
"id": "2",
"source": "4",
"target": "5"
},
{
"input": {
"type": "Dtmf",
"value": "2"
},
"type": "Input",
"id": "3",
"source": "4",
"target": "6"
},
{
"input": {
"type": "Speech",
"value": "Stocks"
},
"type": "Input",
"id": "4",
"source": "4",
"target": "7"
}
]
}
Appendix B: Example with an empty model
The example contains an empty model boilerplate that can be imported into the CX Model Editor.
{
"schemaVersion": "3.0",
"name": "New Model Name",
"entryModule": "1",
"language": "en-US",
"crawlSettings": {
"transcriberSpeaker": {
"name": "English (USA) - Speaker Independent v1"
}
},
"testDefaults": {
"mpsrLevel": {
"minor": 80.0,
"major": 60.0
},
"pesqLevel": {
"referenceAudio": null,
"minor": 3.6,
"major": 3.2
}
},
"modules": [
{
"id": "1",
"name": "Main",
"entryElement": "E8",
"elementRefs": [
"E8",
"25"
]
}
],
"elements": [
{
"type": "Entry",
"id": "E8",
"phoneNo": "555131412",
"callingPhoneNo": "",
"name": "555131412"
},
{
"type": "Menu",
"id": "25",
"prompt": {
"text": "",
"userVerified": false,
"source": "User"
},
"name": "N555131412"
}
],
"links": [
{
"type": "Sequence",
"id": "1",
"source": "E8",
"target": "25"
}
]
}
Comments
0 comments
Please sign in to leave a comment.