Flow Specification
Search…
Flow Specification
1.0.0-rc3
Introduction
Changelog
Glossary and Definitions
Flow Fundamentals
Expressions
Layers
Layer 1: Core
Layer 2: Console IO
Layer 3: Mobile Primitives
Layer 4: Smart Devices
API Specification
Powered By GitBook
Layer 3: Mobile Primitives
Layer 3 contains the specification for I/O blocks that represent discrete single actions, that have direct analogues across several channels used in mobile messaging (e.g. IVR, SMS, USSD). Support for this layer should be implemented by all engines that target the IVR, TEXT (SMS and USSD), and RICH_MESSAGING modes. These blocks may make use of the Expression Specification for generating output. Higher levels may make use of embedded Layer 3 primitives to describe more advanced functionality.
Namespace: MobilePrimitives

Contents

Message Block

  • Type: MobilePrimitives.Message
  • Suggested number of exits: 1
  • Supported modes: IVR, TEXT, RICH_MESSAGING, OFFLINE
This block presents a single message to the contact. The form of the message can depend on the mode: e.g. a voice recording for the IVR mode, and text for the TEXT mode.

Block config

Key
Description
prompt (resource)
The content to be output. This is a localized resource; it supports parsing of expressions in rendering.

Detailed behaviour by mode

  • SMS (SMS): Sends prompt as an SMS to the contact.
  • USSD (USSD): Displays prompt as the next USSD prompt to the user. (Note on USSD session management: If there are following blocks in the flow, the user has an opportunity to reply with anything to proceed. If there are no following blocks, the contact is prompted to dismiss the session.)
  • IVR: Plays prompt to the contact.
  • RICH_MESSAGING: Display prompt within the conversation with the contact. Optionally, platforms may attach the audio from the prompt resource (if provided) so that the contact can choose to play it.
  • OFFLINE: Display prompt within the session with the contact.

Output behaviour

None

Example

1
{
2
"type": "MobilePrimitives.Message",
3
"name": "welcome_message",
4
"label": "Welcome Message",
5
"exits": [...]
6
"config": {
7
"message": "42095857-6782-425d-809b-4226c4d53d4d"
8
}
9
}
Copied!

Select One Response (Multiple Choice Question) Block

  • Type: MobilePrimitives.SelectOneResponse
  • Suggested number of exits: 1 + default exit (used in case of error or invalid input), or multiple exits based on choices
  • Supported modes: IVR, TEXT, RICH_MESSAGING, OFFLINE
This block obtains the answer to a Multiple Choice question from the contact. The contact must choose a single choice from a set of choices.

Block config

Key
Description
prompt (resource)
The question prompt that should be displayed to the contact, e.g. "What is your favorite kind of ice cream? Reply 1 for chocolate, 2 for vanilla, and 3 for strawberry."
question_prompt (resource, optional)
For instances when the question prompt should be separated from the presentation of choices, e.g. "What is your favorite kind of ice cream?". If included, blocks must provide suitable resources within choices to present the choices on each supported mode. For the IVR mode, they must also provide digit_prompts.
choices (array of choices)
Set of choices to select from. See choices configuration below.

Choices configuration

Each choice in choices has the following elements:
Key
Description
name (string)
Key identifying this choice. This is what will be written into the block output (block.value) when a contact selects this choice, e.g. "chocolate" or "Somewhat Agree".
test (expression)
The first choice with an expression that evaluates to a truthy value is the selected choice. Often this expression would examine the raw response from the contact, e.g. "block.response = 1"
prompt (resource)
Resource used to present/display/announce this choice to contacts, appropriate for the language and mode.

Channel-specific config:

Key
Description
IVR: digit_prompts (array of resources)
An ordered set of audio prompts, with the same length as choices, with content such as "Press 1", "Press 2", "Press 3". This is required when using question_prompt to present choices individually.
This block can be configured to have a single exit, or a number of exits with possibilities based on the response given. The exit specification is as described in Block exits.

Detailed behaviour by mode

  • TEXT (SMS): Send an SMS with the prompt text, according to the prompt configuration in config above, and wait to capture a response. (Lack a response after the flow's configured timeout, or an invalid response: proceed through the default exit.)
  • TEXT (USSD): Display a USSD menu prompt with the prompt text, according to the prompt configuration in config above, then wait to capture the menu response. (Dismissal of the session, timeout, or invalid response: proceed through the default exit.)
  • IVR: Play the prompt, according to the prompt configuration in config above, then wait to capture the DTMF response. (Timeout or invalid response: proceed through the default exit.)
    • When question_prompt is provided, prompt is ignored, and the prompt presented to the contact is generated as follows:
      • "What is your favorite kind of ice cream?" "For chocolate," "Press 1". "For vanilla", "Press 2". "For strawberry," "Press 3".
      • <question_prompt> <choices["chocolate"]> <digit_prompts[0]> <choices["vanilla"]> <digit_prompts[1]> <choices["strawberry"]> <digit_prompts[2]>
  • RICH_MESSAGING: Display the prompt text according to the prompt configuration in config above. Platforms may wait to capture a text response, or display rich menu items for each choice and wait to capture a menu choice. (If displaying menu items, platforms should display only question_prompt.) (Timeout or invalid response: proceed through the default exit.)
  • OFFLINE: Display the prompt text according to question_prompt, and a menu of items for all choices. Wait to capture a menu selection.

Output behaviour

This block writes the name of the selected choice to the output variable corresponding to the name of the block.

Example

1
{
2
"type": "MobilePrimitives.SelectOneResponse",
3
"name": "favorite_ice_cream",
4
"label": "Favorite Ice Cream",
5
"exits": [
6
{
7
"uuid": "95fd672c-92e9-4352-b761-7008b27cbe26",
8
"test": "block.value = chocolate",
9
"name": "chocolate",
10
},
11
{
12
"uuid": "9fab760c-a680-4e40-83b7-9b3f8c66ccdb",
13
"test": "block.value = vanilla",
14
"name": "vanilla",
15
},
16
{
17
"uuid": "d99d43ec-6f0a-42b4-97f9-aa1c50ddebe0",
18
"test": "block.value = strawberry",
19
"name": "strawberry",
20
}
21
{
22
"uuid": "78012084-b811-4177-88ea-5de5d3eba57d",
23
"default": true,
24
"name": "Default",
25
},
26
],
27
"config": {
28
"prompt": "42095857-6782-425d-809b-4226c4d53d4d",
29
"choices": [
30
{
31
"name": "chocolate",
32
"prompt": "b0f6d3ec-b9ec-4761-b280-6777d965deab",
33
"test": "OR(
34
AND(flow.mode = 'IVR', block.response = 7),
35
AND(flow.mode != 'IVR',
36
OR(
37
AND(flow.language = 'eng', OR(block.response = 1, block.response = 'chocolate')),
38
AND(flow.language = 'fre', OR(block.response = 1, block.response = 'chocolat'))
39
)
40
)
41
)"
42
},
43
{
44
"name": "vanilla",
45
"prompt": "b75fa302-8ff7-4f49-bf26-8f915e807222",
46
"test": "OR(
47
AND(flow.mode = 'IVR', block.response = 8),
48
AND(flow.mode != 'IVR',
49
OR(
50
AND(flow.language = 'eng', OR(block.response = 2, block.response = 'vanilla')),
51
AND(flow.language = 'fre', OR(block.response = 2, block.response = 'vanille'))
52
)
53
)
54
)"
55
},
56
{
57
"name": "strawberry",
58
"prompt": "22619b04-b06d-483e-af83-ee3ba9c8c867",
59
"test": "OR(
60
AND(flow.mode = 'IVR', block.response = 9),
61
AND(flow.mode != 'IVR',
62
OR(
63
AND(flow.language = 'eng', OR(block.response = 3, block.response = 'strawberry')),
64
AND(flow.language = 'fre', OR(block.response = 3, block.response = 'fraise'))
65
)
66
)
67
)"
68
}
69
]
70
}
71
}
72
[...]
73
​
74
"resources": [
75
{
76
uuid: "42095857-6782-425d-809b-4226c4d53d4d",
77
values: [
78
{
79
language_id: "eng",
80
modes: ["SMS", "USSD"],
81
content_type: "TEXT",
82
mime_type: "text/plain",
83
value: "What is your favorite kind of ice cream? Reply 1 for chocolate, 2 for vanilla, and 3 for strawberry."
84
},
85
{
86
language_id: "fre",
87
modes: ["SMS", "USSD"],
88
content_type: "TEXT",
89
mime_type: "text/plain",
90
value: "Quelle est votre sorte de crème glacée préférée ? Répondez 1 pour le chocolat, 2 pour la vanille et 3 pour la fraise."
91
},
92
{
93
language_id: "eng",
94
modes: ["IVR"],
95
content_type: "AUDIO",
96
mime_type: "audio/wav",
97
value: "favorite_ice_cream_question.wav"
98
},
99
{
100
language_id: "fre",
101
modes: ["IVR"],
102
content_type: "AUDIO",
103
mime_type: "audio/wav",
104
value: "question_creme_glacee_preferee.wav"
105
},
106
]
107
},
108
{
109
uuid: "b0f6d3ec-b9ec-4761-b280-6777d965deab",
110
values: [
111
{
112
language_id: "eng",
113
modes: ["SMS", "USSD"],
114
content_type: "TEXT",
115
mime_type: "text/plain",
116
value: "Chocolate"
117
},
118
{
119
language_id: "fre",
120
modes: ["SMS", "USSD"],
121
content_type: "TEXT",
122
mime_type: "text/plain",
123
value: "Chocolat"
124
}
125
]
126
},
127
{
128
uuid: "b75fa302-8ff7-4f49-bf26-8f915e807222",
129
values: [
130
{
131
language_id: "eng",
132
modes: ["SMS", "USSD"],
133
content_type: "TEXT",
134
mime_type: "text/plain",
135
value: "Vanilla"
136
},
137
{
138
language_id: "fre",
139
modes: ["SMS", "USSD"],
140
content_type: "TEXT",
141
mime_type: "text/plain",
142
value: "Vanille"
143
}
144
]
145
},
146
{
147
uuid: "22619b04-b06d-483e-af83-ee3ba9c8c867",
148
values: [
149
{
150
language_id: "eng",
151
modes: ["SMS", "USSD"],
152
content_type: "TEXT",
153
mime_type: "text/plain",
154
value: "Strawberry"
155
},
156
{
157
language_id: "fre",
158
modes: ["SMS", "USSD"],
159
content_type: "TEXT",
160
mime_type: "text/plain",
161
value: "Fraise"
162
}
163
]
164
},
165
{
166
uuid: "10a11345-9575-4e4a-bf61-0e04758626e7",
167
values: [
168
{
169
language_id: "eng",
170
modes: ["SMS", "USSD"],
171
content_type: "TEXT",
172
mime_type: "text/plain",
173
value: "Invalid"
174
},
175
{
176
language_id: "fre",
177
modes: ["SMS", "USSD"],
178
content_type: "TEXT",
179
mime_type: "text/plain",
180
value: "Invalide"
181
}
182
]
183
},
184
]
Copied!

Select Many Responses (Multiple Choice Question) Block

  • Type: MobilePrimitives.SelectManyResponses
  • Suggested number of exits: 1 + default exit (used in case of error or invalid input), or multiple exits based on choices
  • Supported modes: IVR, TEXT, RICH_MESSAGING, OFFLINE
This block obtains the answer to a Multiple Choice question from the contact. The contact can select from zero to many options from a set of choices.

Block config

Key
Description
prompt (resource)
The question prompt that should be displayed to the contact, e.g. "What kinds of ice cream do you like: chocolate, vanilla, strawberry? Select all that apply."
question_prompt (resource, optional)
For instances when the question prompt should be separated from the presentation of choices, e.g. "What is your favorite kind of ice cream?". If included, blocks must provide suitable resources within choices to present the choices on each supported mode. For the IVR mode, they must also provide digit_prompts.
choices (array of choices)
Set of choices to select from. See choices configuration below.
minimum_choices (integer, optional)
The minimum number of choices the Contact must select to proceed. Default if not provided: 0.
maximum_choices (integer, optional)
The maximum number of choices the Contact can select. Default if not provided: unlimited (ie: the total number of choices).

Choices configuration

Each choice in choices has the following elements:
Key
Description
name (string)
Key identifying this choice. This is what will be written into the block output (block.value) when a contact selects this choice, e.g. "chocolate" or "Somewhat Agree".
test (expression)
Any choice with an expression that evaluates to a truthy value is a selected choice. Often this expression would examine the raw response from the contact, e.g. "block.response = 1"
prompt (resource)
Resource used to present/display/announce this choice to contacts, appropriate for the language and mode.
This block can be configured to have a single exit, or a number of exits with possibilities based on the response given. The exit specification is as described in Block exits.

Detailed behaviour by mode

  • TEXT (SMS): Send an SMS with the prompt text, according to the prompt configuration in config above, and wait to capture multiple responses. (Lack of the right number of responses after the flow's configured timeout, or an invalid response: proceed through the default exit.)
  • TEXT (USSD): Display a USSD menu prompt with the prompt text, according to the prompt configuration in config above, then wait to capture text describing multiple choices. (Dismissal of the session, timeout, or invalid response: proceed through the default exit.)
  • IVR: Play the prompt, according to the prompt configuration in config above, then wait to capture multiple DTMF responses. Implementations may choose to optimize the user experience for additional guidance on answering multiple options. (Timeout or invalid response: proceed through the default exit.)
    • When question_prompt is provided, prompt is ignored, and the prompt presented to the contact is generated as follows:
      • "What is your favorite kind of ice cream?" "For chocolate," "Press 1". "For vanilla", "Press 2". "For strawberry," "Press 3".
      • <question_prompt> <choices["chocolate"]> <digit_prompts[0]> <choices["vanilla"]> <digit_prompts[1]> <choices["strawberry"]> <digit_prompts[2]>
  • RICH_MESSAGING: Display the prompt text according to the prompt configuration in config above. Platforms may wait to capture a text response, or display rich menu items for each choice and wait to capture a menu choice. (If displaying menu items, platforms should display only question_prompt.) (Timeout or invalid response: proceed through the default exit.)
  • OFFLINE: Display the prompt text according to question_prompt, and a menu of items for all choices. Wait to receive a menu confirmation.

Output behaviour

This block writes an array of names of the selected choices to the output variable corresponding to the name of the block.

Example

1
[...]
2
{
3
"type": "MobilePrimitives.SelectManyResponses",
4
"name": "ice_cream_order",
5
"label": "Ice Cream Order",
6
"exits": [
7
{
8
"uuid": "95fd672c-92e9-4352-b761-7008b27cbe26",
9
"test": "block.value = 'chocolate'",
10
"name": "chocolate",
11
},
12
{
13
"uuid": "9fab760c-a680-4e40-83b7-9b3f8c66ccdb",
14
"test": "block.value = 'vanilla'",
15
"name": "vanilla",
16
},
17
{
18
"uuid": "d99d43ec-6f0a-42b4-97f9-aa1c50ddebe0",
19
"test": "block.value = 'strawberry'",
20
"name": "strawberry",
21
}
22
{
23
"uuid": "78012084-b811-4177-88ea-5de5d3eba57d",
24
"default": true,
25
"name": "Default",
26
},
27
],
28
"config": {
29
"prompt": "42095857-6782-425d-809b-4226c4d53d4d",
30
"minimum_choices": 1,
31
"choices": [
32
{
33
"name": "chocolate",
34
"prompt": "b0f6d3ec-b9ec-4761-b280-6777d965deab",
35
"test": "OR(
36
AND(flow.mode = 'IVR', block.response = 7),
37
AND(flow.mode != 'IVR',
38
OR(
39
AND(flow.language = 'eng', OR(block.response = 1, block.response = 'chocolate')),
40
AND(flow.language = 'fre', OR(block.response = 1, block.response = 'chocolat'))
41
)
42
)
43
)"
44
},
45
{
46
"name": "vanilla",
47
"prompt": "b75fa302-8ff7-4f49-bf26-8f915e807222",
48
"test": "OR(
49
AND(flow.mode = 'IVR', block.response = 8),
50
AND(flow.mode != 'IVR',
51
OR(
52
AND(flow.language = 'eng', OR(block.response = 2, block.response = 'vanilla')),
53
AND(flow.language = 'fre', OR(block.response = 2, block.response = 'vanille'))
54
)
55
)
56
)"
57
},
58
{
59
"name": "strawberry",
60
"prompt": "22619b04-b06d-483e-af83-ee3ba9c8c867",
61
"test": "OR(
62
AND(flow.mode = 'IVR', block.response = 9),
63
AND(flow.mode != 'IVR',
64
OR(
65
AND(flow.language = 'eng', OR(block.response = 3, block.response = 'strawberry')),
66
AND(flow.language = 'fre', OR(block.response = 3, block.response = 'fraise'))
67
)
68
)
69
)"
70
}
71
]
72
}
73
}
Copied!

Numeric Response Block

  • Type: MobilePrimitives.NumericResponse
  • Suggested number of exits: 1 + default exit (used in case of error or invalid input), or multiple based on ranges of interest
  • Supported modes: IVR, TEXT, RICH_MESSAGING, OFFLINE
This block obtains a numeric response from the contact.

Block config

Key
Description
prompt (resource)
The question prompt that should be displayed to the contact, e.g. "How old are you? Please reply with your age in years."
validation_minimum (number, optional)
The minimum value (inclusive) that will be accepted as a response to this block; responses less than this will proceed through the default exit.
validation_maximum (number, optional)
The maximum value (inclusive) that will be accepted as a response to this block; responses greater than this will proceed through the default exit.

Channel-specific config:

Key
Description
IVR: max_digits (number)
After receiving this many digits, do not wait for any more; accept the digits entered so far as the complete response.
This block can be configured to have a single exit, or a number of exits with possibilities based on the range of the numeric response given. The exit specification is as described in Block exits.

Detailed behaviour by mode

  • TEXT (SMS): Send an SMS with the prompt text, according to the prompt configuration in config above, and wait to capture a response. (Lack a response after the flow's configured timeout, or an invalid response: proceed through the default exit.)
  • TEXT (USSD): Display a USSD menu prompt with the prompt text, according to the prompt configuration in config above, then wait to capture the menu response. (Dismissal of the session, timeout, or invalid response: proceed through the default exit.)
  • IVR: Play the prompt, according to the prompt configuration in config above, then wait to capture the DTMF response. (Timeout or invalid response: proceed through the default exit.)
  • RICH_MESSAGING: Display the prompt text according to the prompt configuration in config above. Platforms may wait to capture a text response, or display a numeric entry widget and wait to capture a response. (Timeout or invalid response: proceed through the default exit.)
  • OFFLINE: Display the prompt text according to the prompt configuration in config above, and display a numeric entry widget. Wait to capture a response.

Output behaviour

This block writes the numeric value received to the output variable corresponding to the name of the block.

Example

1
[...]
2
{
3
"type": "MobilePrimitives.NumericResponse",
4
"name": "patient_age",
5
"label": "How old are you?",
6
"exits": [...],
7
"config": {
8
"prompt": "986a0f39-bfdf-4aa0-9fe2-28c90f422e1f",
9
"validation_minimum": 0,
10
"validation_maximum": 120,
11
"IVR": {
12
"max_digits": 3
13
}
14
}
15
}
Copied!

Open Response Block

  • Type: MobilePrimitives.OpenResponse
  • Suggested number of exits: 1 + default exit (used in case of error or invalid input), or multiple based on patterns of interest
  • Supported modes: IVR, TEXT, RICH_MESSAGING, OFFLINE
This block obtains an open-ended response from the contact. Dependent on the mode, this is a TEXT response, audio recording, or other type of media recording (e.g. video).

Block config

Key
Description
prompt (resource)
The question prompt that should be displayed to the contact, e.g. "Please leave
us feedback on your experience at the Children's Hospital."

Channel-specific config:

Key
Description
IVR: max_duration_seconds (number)
The maximum duration to record for, before proceeding to the next block.
TEXT: max_response_characters (number, optional)
The maximum number of characters to prompt for and accept. (If not provided, no limit.)
This block can be configured to have a single exit, or a number of exits with possibilities based on patterns in the response given. The exit specification is as described in Block exits.

Detailed behaviour by mode

  • TEXT (SMS): Send an SMS with the prompt text, according to the prompt configuration in config above, and wait to capture a response. (Invalid/empty response: proceed through the default exit.)
  • TEXT (USSD): Display a USSD menu prompt with the prompt text, according to the prompt configuration in config above, then wait to capture the menu response. (Invalid/empty response: proceed through the default exit.)
  • IVR: Play the prompt, according to the prompt configuration in config above, then record the user's response. (Timeout with nothing recorded: proceed through the default exit.)
  • RICH_MESSAGING: Display the prompt text according to the prompt configuration in config above, and wait to capture a text response or an upload (audio, video) from the contact. (Invalid/empty response: proceed through the default exit.)
  • OFFLINE: Display the prompt text according to the prompt configuration in config above, and display a text entry widget. Wait to capture a response.

Output behaviour

For TEXT, OFFLINE, and RICH_MESSAGING modes that capture a text response, this block writes the text received to the output variable corresponding to the name of the block. For responses captured as media (IVR, RICH_MESSAGING) the ID or URL of the recording is written.

Example

1
[...]
2
{
3
"type": "MobilePrimitives.OpenResponse",
4
"name": "OpenResponseFeedback",
5
"label": "Patient Feedback",
6
"semantic_label": "patient_feedback",
7
"exits": [...],
8
"config": {
9
"prompt": "b969cd54-c894-4f5a-891e-f1b24e32982b",
10
"IVR": {
11
"max_duration_seconds": 120
12
},
13
"TEXT": {
14
"max_response_characters": 160
15
}
16
}
17
}
Copied!
Previous
Layer 2: Console IO
Next
Layer 4: Smart Devices
Last modified 3mo ago
Copy link
Contents
Contents
Message Block
Block config
Detailed behaviour by mode
Output behaviour
Example
Select One Response (Multiple Choice Question) Block
Block config
Detailed behaviour by mode
Output behaviour
Example
Select Many Responses (Multiple Choice Question) Block
Block config
Detailed behaviour by mode
Output behaviour
Example
Numeric Response Block
Block config
Detailed behaviour by mode
Output behaviour
Example
Open Response Block
Block config
Detailed behaviour by mode
Output behaviour
Example