Form builders are among the most popular WordPress plugins. There are dozens of them and with few having millions of active installations. Some of them are simple while others are powerful no-code tools allowing you to build amazing functionalities through them. In this article we will demonstrate how your users can access your forms through Amazon Alexa. For this example we are using a form built with Formidable Forms plugin (free version).
This article is followed with the attached Convoworks service and Formidable Form definitions which you can import into your system. In the article itself, we will just cover how to enable the skill and point out a few important parts in it.
Use case - Exercise Log
Let's say that you have a fitness website where your users can record their own activity and track progress. Now, instead of opening a web browser, your users will be able to save exercise results through Amazon Alexa skill - using voice only.
Besides adding a new log entry, the skill can give you information about the last exercise, it tracks your maximum distance and you are able to delete the last entry. That way we covered most of the form operations you need and it should be rather easy to reuse examples in your own project.
The example form we used for our skill is quite similar to the Exercise Log Form Template available in the plugin premium version. In our example we skipped date/time and the comment fields. We also changed field keys to be readable (instead of having hash as a key) and we used just plain textual fields.
Prerequisites
There are several things to check and set up before you continue.
1. Publicly accessible WordPress installation
Your server has to be able to accept request from Amazon. If you do not have server on your own, you can use online WordPress testing tools like InstaWP. The second option is to install a tunnel and use your local installation.
2. Installed Formidable Forms plugin
Just go to your plugin installer and add Formidable Form Builder plugin.
3. Convoworks WP - Installed and connected to Alexa
Please make sure that your Convoworks plugin is linked and that you are able to create Alexa skills. You can find more on that in Amazon Alexa platform configuration or you can watch our Connect to Amazon and create your first Alexa skill video tutorial.
Import and configure Exercise log Alexa skill
Few steps to import all definitions, eventual configuration and make the skill work.
1. Import exercise log form into the Formidable Forms
You can import the attached xml form definition (below). To build this form we used regular text editors for all fields except the Activity, which is a radio selector. When communicating with form builders, we prefer keys over ids. Keys are persistent, while ids will vary from installation to installation. Here are the form and field keys we used in our example. Form is exerciselog, while fields are el_activity, el_calories, el_distance, el_max_pulse, and el_rest_pulse.
Formidable Forms definition (XML)
2. Create Exercise Log Convoworks service
Start a new service in Convoworks, and select Import from file option. Use the service definition you can download below. If your form uses different keys for form and fields, navigate to the Variables view and adjust values. You might also consider adjusting values for the app name (if you changed it) and the test user. We'll cover more on test user usage in Resolving the current user section below.
Convoworks service definition (JSON)
3. Connect it to Alexa and enable account linking
Now go to Configuration / Amazon Alexa in Convoworks. Check the Enable Account Linking for Alexa Skill option and disable the Allow users to enable skill without account linking. Save and wait for a minute until the service is fully built on Amazon.
4. Link account in your Alexa app
Open your Alexa app, navigate to Your skills / Dev skills. Press on the Settings button and link account. By doing it, each request that comes through Alexa to our skill will have an OAuth token, which will enable us to authenticate the current user.
You can find more on it in our Amazon Alexa account linking article.
Test your new Alexa skill
If you have an Echo device, invoke the skill and try to use it. You can also try to test it through the ASK console. This way you can "chat" with your skill using their Test view.
You can also use Convoworks Test view which is a handful tool because it allows you to peek into all variables existing during the current request execution.
Few words about skill functionality.
- Skill distinguishes between first time and returning users, so some responses are slightly different. To try again first time use, disable and enable skill again.
- You can just open the skill, Alexa, open exercise log and follow the workflow step by step.
- You can add additional command while invoking the skill: Alexa, ask exercise log to record my running exercise. In this case you will automatically be in the new entry workflow.
- Once you have entries, you can get more info on last entry and ability to delete it.
- You can ask for help.
Few significant parts to check
There are several parts in our service that you should check and get to know how to use. Some parts are related to the form data while others are related to the general features you can use in Convoworks.
Initializing data
When the skill starts, we want to do some checks and preload some data that will be required in our workflow.
Navigate to the Session start step in Convoworks editor and check the Pre-dispatch Flow section. This flow is executed when skill is started (new session starts). It will be executed no matter if the skill is opened regularly (just invocation name) or with additional command. As you can see we are using it to check the current user, load last entry data and to initiate a new entry.
Hint: You can click on a fragment name to navigate to its definition.
Resolving the current user
Our service works only for known users, so in the Resolve user fragment we are trying to load user data and if it fails, we are ending a session.
Init current auth user element will load user data if the account is properly linked. Click on the element and check its help (on right side) for more details.
The if element at the beginning serves to enable ability to test skill even in Convoworks test view, which does not support account linking. We are checking against a predefined device id that comes with the request (admin-chat). If we detect that it is a test view call, we are using the TEST_USER_ID which can be adjusted in the variables view.
Please note that the user_id is stored in the session scope, meaning that it will be available through all subsequent calls.
Formidable Forms context
This is the actual adapter that enables us to use the Formidable Forms plugin. By entering and accessing data through a plugin infrastructure (instead of just performing SQL queries), we are ensuring that all plugin actions and filters will be applied. That way if you hook up some additional actions to your Formidable form, they will be triggered through Alexa skill, just as it would through the default web interface.
Here we are setting the id for the context (so that other form elements are able to reference it), with which form we are working and the user id which will be used when creating entries.
Check the component’s help to learn about some Formidable Forms specifics.
Loading the last entry
For loading previous entries we are using Search Form Entries element. Here we are filtering form entries created by the logged user and making sure that we load just a single, the last one.
In case when there were existing entries, we are performing an additional query to get the maximum distance made in previous exercises. For that we are using WP DB Element, a generic component for accessing any WordPress database table. Please note how we can reference the context and call methods on it - in this case to get numeric ids from a given field and form keys.
Saving the form entry
Through the conversation workflow we are navigating through several steps and collecting data. Once the user confirms it, we can try to save it. We are doing that on the Entry - Confirm step using the Create Form Entry element.
When you are gathering user data through the skill, you have to take care that the data is valid. If it is not it might happen that the entry creation fails due the validation errors. In such a case, Validation error flow will be executed.
Deleting the form entry
Our Last exercise info step informs the user that it can delete the last entry. For that we are using the Delete Form Entry element, which besides context id of the form plugin implementation, requires the id of the entry which will be deleted.
After the entry is deleted, we will reload the last entry info and read that info back.
Global and local help
We have one global, default help which informs the user with basic instruction on how to use skill. This definition can be found in Service processors step, which contains processors which should be always considered for the execution.
However, you can find processors which are catching HelpIntent on the Entry . Activity and Entry . Pulse steps. That means that if the user is on one of those two steps, it will trigger this local processor and not the one in service processors.
If you are using WordPress form builders, think of the use case which might be convenient to be used with voice. The one which you or your users would like to access often. The frequent use is ideal for voice.
This example requires account linking, but you can create a skill which allows public access (e.g. school league results) or you can even ask users to access their Amazon profile data (name, email) and add to the mailing list. Of course, with their permission to do that.
To find more about Convoworks forms package and philosophy behind, at our Forms package for Convoworks at GitHub.
If you have any problems or questions, drop a comment below or contact us through the contact form.
Top comments (0)