Elements are the most versatile component types in Convoworks. They are executed sequentially and can be nested inside one another. You can use them to output responses to users, load data, manipulate variables and as control structures (IF, Then, LOOP, INCLUDE, GOTO …).
There is no strict separation but most elements can be broken down into three main types:
- Display – allows you to output speech or text.
- Data – for fetching data from different sources
- Control structures – for directing the flow of the service and working with variables.
Display
Text Response
The Text response element takes input Text and outputs it to the user either as text or speech, depending on the platform. You can choose from two response types: Default or Reprompt.
The Reprompt type is for handling cases where the user doesn’t provide a response. If you have a Reprompt defined, the system waits for a response and prompts the user again instead of exiting.
You can use SSML in the Text field to tune up audio response and you can also output variable values using expression language. To learn more about expression language and how to use it visit this link: Expression language
The Text response element offers Alexa-only customizations like Domain, Emotion, and Emotion Intensity which help you create an even better voice experience.
Data
HTTP Client
The HTTP client element performs an HTTP request to a specified Endpoint URL. It saves the received result body under the Result name.
The result can be saved under different Scope types – Session, Installation, or Request and either as a Service Param or a Block param.
You can learn more about scope types in the Expression Language guide.
The HTTP client element lets you select either the GET or POST method in the HTTP method dropdown. And depending on the request, you can also send Headers, Parameters, or a Request body JSON.
You can select the Content Type to check for in the headers. The default option AUTO can be replaced by the JSON Content Type. Also, you can enter Timeout to adjust how long a request should wait for a response in seconds.
The Cache Timeout value indicates the expiration time for a cache. This value is also expressed in seconds.
The HTTP Client element has two flows – OK and NOK. The OK flow is executed if the request was successful, and the NOK if it wasn’t.
You can access the result body in the OK flow: ${resultName.body.valueYouWantToAccess}.
To access the response status code and error messages use this syntax: ${resultName.status}.
Control structures
GOTO
The GOTO element stops current block execution and continues with the read flow of the selected block. You select the next block from the Block dropdown. You can call the same block again or select the current state, meaning read the block again.
To learn more about blocks, read our Blocks guide.
You also have the option to run the Previous state – call the previous block. However, these options, excluding calling the next block, can only be executed successfully from the process or the fallback flow of the current block.
Before trying to go back to the Previous state it’s best to test if the ${state_previous} variable was actually set.
Read Block Again
The Read block again element runs the current block again starting with the read phase. The element has no properties.
Run Once
The Run Once element runs its Children elements either once per Session or Installation. It only has a Run once per dropdown property.
It can be used for running an element or a collection of elements only once per device installation or once per each session.
It has two containers – Children and Else. The Else container is run if it’s not empty and the Children container’s properties don’t apply.
INCLUDE
The INCLUDE element, not to be confused with the INCLUDE component in the Process section, includes and reads only a read phase fragment. You select the fragment’s name in the Read fragment name dropdown.
IF
The IF element evaluates whether an expression entered in the Test field is true or false. If the expression evaluates to true the Then container is executed. You can place elements in the Else container to execute if the same expression is false.
To use the ELSEIF container, you need to place the ELSEIF element in it.
ELSE IF
The ELSEIF element isn’t a standalone element and can only be used inside the ElseIF container of the IF element. Otherwise, it’s pretty similar to the IF element.
It evaluates whether an expression entered in the Test field is true or false. If the expression evaluates to true the Then container is executed.
LOOP
The LOOP element iterates over items in a collection. For each iteration, the element stores the item in the Data collection item name variable. Using the Data collection item name variable, you can access the current item’s value, index, natural index, and check if it’s the first or the last item in the collection.
You have to enter the array expression that you want to loop through in the Items field. You can also Name the LOOP element thus making it more readable.
Adding Offset for the number of items to skip, starting from the beginning of the array, is optional, as well as entering Limit for limiting the number of iterations.
The element has the Elements container in which you can place any number of other elements.
FOR
The FOR element is also a loop, but instead of items it iterates over a predefined set of numbers and executes Elements in the container of the same name once for each value.
You enter the iteration number in the Count field and using the Status variable name you can access the current iteration index and natural number as well as check if it’s the first or the last iteration.
Lastly, to improve readability, you can Name the element.
END Session
The END session element ends the session and exits the service. It sends the end session signal to the platform or the device that is being used.
Other
Set Parameter
Runtime variables are set using the Set parameter element. You choose the aforementioned Scope type which determines the lifespan of the variable and you enter the variable as a name-value pair in the Properties field. You can add as many variables as you like by clicking the Add property button.
Both the name and the value fields support expression language, and in some cases, they require it, like setting values that are not of the string type.
You can use the Set Parameter element to set complex data structures like arrays and multidimensional arrays.
Element Randomizer
The Element randomizer picks one child element at random and executes it. You can place the elements you want to randomize in its Elements container.
You can choose between two Element storage modes: Wild or Smart.
- Wild – picks random output every time and executes it
- Smart – picks different random output every time and executes it
The Scope type option is primarily used for the Smart mode’s output. Lastly, you can Name the element to improve readability.
Editor Comment
The Editor comment is a simple element that is only used to display a comment in the Convoworks Editor.
