May 24, 2022

Create company directory Alexa skill for your business – No coding required

People search the internet to get answers and voice search is steadily becoming a common way to get answers to questions. In fact, according to a PwC survey, 71% of consumers would rather use a voice assistant to search for something rather than type it into a search engine.

Why not utilize voice further, and have a voice assistant directly answer those questions? The question and answer format of FAQs is suitable for the conversational nature of voice assistants and their applications.

On account of that, we created a Company Directory skill with placeholder Convoworks content that you can modify to answer your own company’s frequently asked questions and increase customer engagement.

In the next sections, you’ll learn how the skill works and how to modify it to suit your own needs.

What does the skill do?

Company Directory is primarily intended as an Alexa skill that lets your customers ask questions about your business or product.

We set up the service as a Convoworks Directory. We’ll get to the part where you turn it into your company’s FAQ later on in this post. First, let’s touch on how the service works in its current state.

After the introductory message, the user is asked what question they have. If the question is not matched to available questions, they are given an example of what they can ask. The user is also notified that they can ask for suggestions.

Note that the reprompt and fallback texts, as well as the introductory message, differ slightly depending on if it’s the first-time user or a returning one.

After the user gets an answer to their question, they are asked what else they wanted to know. The user can always answer with ‘nothing’ and the service will exit.

They can also answer with ‘I don’t know, ‘I’m not sure’ etc. and they’ll be redirected to the Suggestions flow. There, they’ll first be offered one suggestion, and if they refuse that one, the next two suggestions.

The questions that were already asked, or suggested in the current session are excluded from suggestions.

If the user still can’t decide, the suggested information is picked for them and the service moves on to the facts flow. If, on the other hand, the user refuses all suggestions, the service plays a goodbye message and exits.

After the user has picked a suggestion, we proceed to the Facts flow. There, after the chosen suggestion is read first, the user is asked if they want to hear more. If the answer is yes, another company FAQ information is read out to the user, and so on until the system runs out of things to say. The user can then start over the Facts flow or exit the app. As is the case in the Suggestions flow, information that the user has already asked about is excluded from this flow.

If the user has answered ‘no’ to the ‘Hear more?’ question, the service exits after a goodbye message.

As you can see, the service can be divided into three flows, the main one being the FAQ flow, with the two supporting sub-flows there to help struggling users.

How do I set it up?

We’ll provide a Company Directory service definition and you just need to follow these simple steps to set the service up.

Service definition

Navigate to Add new service view in Convoworks WP and select Import from file option. Upload the service definition from the link above. After that, navigate to the Configuration view and publish it to Amazon.

If this is your first time using Convoworks you might want to check out our “Connect to Amazon and create your first Alexa skill tutorial” from Convoworks Basics video series.

Lastly, after the changes have taken effect, you can test the service in the Convoworks Test chatbox to make sure it’s good to go.

Now, let’s take a look at how to make changes to the service.

How do I modify it?

As you can see from the image above, the service’s flows are reflected in the block names. The main block is the FAQ one. The FAQ – home block leads to the Suggestions block when the user is not sure what they can’t or want to ask. If the user accepts the first suggestion, they move on to the Suggestions – yes – facts block. And if they refuse the suggestion, they are given the next two suggestions in the Suggestions – no block. After they pick one of the two suggestions in the Suggestions – no block, they return back to the FAQ – home block.

Most of the modifications you’ll have to make to the service will be limited to the JSON file we’ll provide.

You’ll have to upload that  JSON file and paste the URL link into the FAQ_FILE_PATH variable value. The JSON needs to be in the following format:

You can download it below.

Company FAQ JSON

The JSON file is loaded and separated into two arrays at the beginning of each session in the Pre-Dispatch flow of the Session start block. The body array, contains both the suggestions_no and all values, while the FAQ_array contains only the all category values.

The next step is to replace all the values (except id values) with your own. You can also delete groups of values sorted by id or add additional groups, just keep in mind that for each group you delete in the all category, you’ll need to delete the corresponding intent later on. Or if you add additional groups with new ids, you’ll also need to create and add intents for them.

Most of the data is in the all category. faq_suggestion belongs to the FAQ – home block where if the user question is not recognized, an appropriate suggestion will be offered in the block fallback.


answer values are used in the Service processors Questions fragment to connect JSON id with intent faq_id and give the appropriate answer to the user question.

They are also used to form the facts array for the Suggestions – yes – facts block

The values with the suggestion prefix are used in the Suggestions block only. As you can probably guess, suggestions_no, which has a separate category, is only used in the Suggestions – no block. suggestions_no stores two ids that correspond to the two suggestions that are offered to the user.

After you’ve prepared the JSON file, you’ll need to upload it and paste the link to the FAQ_FILE_PATH variable value. On the Variables panel, you’ll also find all the variables used in the text. You should change their values as well.

The second step would be modifying the FAQ intents. You can see them gathered in the Questions fragment. Each intent has a faq_id value that corresponds to the id value in the JSON. If you’ve added new groups with corresponding ids you’ll need to place a new intent with the corresponding faq_id there as well.

Head over to Intent Model to view all the available intents. You should rename intents to suit your own company, and change, delete or modify their utterances as well. After you’ve modified the intent name, you’ll need to update it in the Questions fragment too. Lastly, you’ll need to propagate the service in order for the changes to take effect. One more thing concerning the intents, if you experience any issues with intent overmatching because of the sheer number of intent and similarity in utterances, if paring down doesn’t work, we recommend experimenting with the Interaction Model Sensitivity in the Configuration settings.

The last step will require a bit more service editing, as you’ll need to make some minor changes to the text not listed in JSON. To make things easier, you can find the compiled locations of all the text that potentially requires modification below.

Session start block – Read Phase

Session start block – Fallback

FAQ block – Read Phase

FAQ block – Fallback

Service processors block – Help

What improves the skill’s user experience, but makes it more time-consuming to make modifications to, are those many variations in suggestions and responses. Hopefully, we’ve managed to make the process of adding your own text easier.


This post showcases a skill that makes use of the classic FAQ and adapts it for use with Alexa. The Company Directory skill lets your customers ask questions about your business or product with additional flows helping struggling customers.

The service preset we offer for download is a Convoworks Directory skill, but with modifications, it can become your business’ or company’s skill, going beyond the classic FAQ format, and thus increasing your customer engagement.

Petra Gal

Petra Gal

VUI Designer with two years of experience in designing conversational interfaces, including Alexa skills and IVRs. Certified by Conversation Design Institute in Conversation Design and Career Foundry in VUI Design. Experienced in creating customer-focused solutions that are intuitive and accessible.

Tihomir Dmitrović

Tihomir Dmitrović

Full stack developer with 20+ years of professional experience, specialized in solving complex problems in a scalable manner. Founded Convoworks, which is a GUI based tool for creating voice and chatbot applications through WordPress.

Aug 10, 2023  | 

How to Modify Your robots.txt to Prevent GPTBot from Crawling Your Site with Convoworks

Introduction Ensuring that your website’s content is accessed on your terms is essential. With an increasing number of web…


Jul 24, 2023  | 

Create Your Dummy API with Convoworks to Streamline Development

Introduction Building on our previous article where we explored synchronizing data with the Tiltify API using WordPress, we’ll now…