Learn how to integrate a basic Conversational Component in a Jovo project.
- A Component's Structure
- Delegating to the Component
- The Response
Conversational Components are small pre-packaged Jovo project snippets, which solve one particular problem and can be seamlessly integrated into your existing project, using the Jovo CLI.
They include the following parts, neatly bundled into an npm package:
- a language model with all the needed intents and entities/slots,
- the handler (logic) for the code fulfilment, and
- the i18n (cms) files that store all the responses/content.
The main benefit of Conversational Components is the saved time. With even seemingly easy tasks, such as retrieving the user's phone number, turning into large time consuming problems, where most people try to find their own solution, Conversational Components try to provide a customizable solution.
In the future, with the help of our community, these components could be used as best-practices for the growing field of voice app development.
Here are a few sample components that are already available:
- get the user's phone number
- get the user's email address
- allow the user to book a calendar meeting with you
- ask the user for their opinion in a survey
In this short tutorial we will go over the process of integrating the
ConductSurvey component into a Hello World example project.
It's a fairly simple component, where you define a set of questions, which the user can answer to with a number between 1 and 5, where 1 is the worst and 5 the best.
A Conversational Component structure should look familiar to you, as it was modeled after a standard Jovo project.
The basic version looks the following:
Their are four parts to every component.
The first part is the handler. It contains the logic, which are the intents in our case.
Second, the config file. It is used to specify the components default config, which can be overwritten using your projects own config file. It provides a way to make small modifications without having to dig deep into the codebase of the component.
On the third sport are the i18n files. As of now we use i18n as the supported form of CMS. Again it provides you with a way to customize the components, this time the responses. An integration with an external CMS is planned.
Last but not least, the index file. It's the core of the component, which is used to export all the other parts.
Although every part is inside a single file here, it's obviously also possible and also recommended to split stuff up the bigger the whole component gets.
We go into more detail about each part of the component inside the documentation, which you can find here.
First of all, we create a new Jovo project:
After that we install the component:
After installing the component you have to load it into your project using the
jovo load command:
It will create a
components folder inside
src/ which will store all the components:
After that have the enable the component using the the
useComponent(...components) function inside our
Every component can be configured using your project's root config file.
The interface for the possible configurations should be documented in the component's README file.
In our case we want to increase the number of questions of the survey to 4 instead of the default 3.
The questions are specified in the i18n files, so we go ahead and replace the placeholder questions:
Now that our component is configured, we can go ahead add the delegation logic to our handler.
To delegate the task to the component, you have to use the
delegate(componentName, delegationOptions) function. It will automatically route to the component's
START intent and which point it will take over.
The only necessary property that you have to add to the
delegationOptions is the
onCompletedIntent. It is used to specify the intent to which the component will route to after it's done.
Now, let's test the first version of our test project in the Jovo Debugger:
As you can see the app now runs through the questions we specified earlier and routes back to the
onCompletedIntent once it's finished. The only thing missing is the response of the component.
While the component goes through the necessary steps to fulfill the task, there are three conditions at which it will route back to the intent you specified in the delegation options.
- the component finished the task
- an error occurred along the way
- the user tried to manually stop the app, e.g.
No matter which reason, the component will always return a response.
The response has the following properties:
||Represents the status of the component. Will be set to
||An object containing the data the component was supposed to collect. The content of the object will be different for each component||
||An error object, which is only present if the status is set to
The response is stored in the respective component's
$response object, which we can access using the new
$components object, a register for every active component.
Now test the app once again and the response should pop up in the console:
Since the component ran through without problems, our response's status is set to
SUCCESSFUL and it also contains the
data object, which is map containing the question number and the user's response, e.g. the user gave the first question a rating of 3.
To not run into any errors, you should always check the status of the response and handle each of them accordingly. For example:
That's all you need to know to get started with Conversational Components.
You can also check out a more complex Conversational Component, which allows your user to schedule meetings using a Google Calendar integration here.