Special thanks to Mark Maestas who provided this tutorial. For more tutorials and skill building services, check out his site at voices.app 

Prerequisites
Please make sure you have an undestanding of:

API Block

Introduction

Voiceflow easy integrates with Airtable for data processing. Utilizing Airtable is an ideal way to store rows of interrelated data and retrieve them into your Alexa skills.

Technical difficulty: easy

This tutorial is designed for beginner Alexa Voice Skill Developers, and no coding experience is required.

Tutorial Scope

This tutorial describes a specific method for retrieving records from an Airtable database (aka “base”) into a Voiceflow project. Using Voiceflow's API block, a GET method is used.

The tutorial also shows you how to use the API block in Voiceflow to retrieve and use data from an Airtable base. Examples:

  • Retrieve a single value from a specific field. A field is similar to a cell in a spreadsheet. Use the field name and a numerical record reference in a Voiceflow block through using a variable.
  • Retrieve one or more field values for a single record.  A record is similar to a row in a spreadsheet. The record contains a set of interrelated values in the fields.  Use the field names and a numerical record reference in an API block.
  • Retrieve one or more field values for multiple records.  Use the field names and numerical record references in an API block.

What this tutorial does NOT cover:

  • Retrieving a randomly selected row of interrelated values. We have a tutorial for that here using Google sheets.
  • Looking up and retrieving a value based on an input parameter.

These additional types of Airtable interactions may be the subject of future tutorials.

Use Case

A database contains multiple rows of data. Each row contains interrelated data stored in multiple fields (in Airtable, a “field” is conceptually similar to a “column” in a spreadsheet).

For example, the Airtable base (database) might contain quotes.  Each record (row) has three fields (columns).  The first field might be the quote, the second field might be the source of the quote, and the third field might be the location where the quote was made.

A Voiceflow project is configured to use an API block to retrieve a value from a single field, a set of interrelated values in multiple fields from a single row, or multiple values stored in multiple fields and rows.  The API Response within the API block would specify numerical and field name parameters.  The returned value(s) are stored in variable(s) for use elsewhere in the Voiceflow project.

What is Airtable?

Airtable Homepage

Airtable is a cloud-based service. The service is considered “Part spreadsheet, part database, and entirely flexible. For Voice developers already familiar with integrating Google Sheets, Airtable is similar in that rows of interrelated data can be retrieved, and spreadsheet-like formulas can be applied.

For creative-types and those on collaborative teams, Airtable is easy to work with, and is an alternative to Amazon’s DynamoDB.

Jeff Blankenburg discusses some additional benefits of Airtable in comparison to DynamoDB in the following article:

Alexa Blogs: How to Make It Easy for Teams to Contribute Content to Your Alexa Skill, by Jeff Blankenburg, April 24, 2018.

If you are new to Airtable, you will need to create an account, and for this tutorial, the free subscription shoud be adequate both for your practice skill as well as your other smaller skills.

Airtable Homepage

Once you have created and logged into Airtable, take a few minutes to review some of the video tutorials, help screens, subscription/pricing options, and terms of use to familiarize yourself with its features.

An excellent starting point is the following page. It contains additional links to a variety of reference materials:

Using Airtable

WARNING!

Airtable offers multiple subscription levels. There is a free subscription that continues beyond the trial period, which can be a nice option if you are not going to be managing large amounts of data. However once you exceed a certain number of records, you will be expected to subscribe to one of the paid plan options.

Be sure to check the current pricing plans and plan limits to confirm Airtable is right for your project’s needs.

What is Voiceflow?

Voiceflow Homepage

Voiceflow is a fast & easy way to build Alexa skills. Their drag & drop tool allows anyone to build simply, or incredibly powerful Alexa skills without coding.

This tutorial will walk you through creating a very simple test project, show you how to upload it as a skill to the Amazon Alexa Developer Console, and then test it. You will NOT need to publish your test skill to the general public as part of completing this tutorial.

If you have never created an Alexa skill before you will first need to create an Amazon Developer account. You can follow the link below and quickly set one up.

Amazon Developer Services and Technologies

You will also need to set up an account with Voiceflow if you are a first time user.

Voiceflow Sign Up

Task Summary

  • PART 1 – Create an Airtable Workspace and Base
  • PART 2 – Populate the Airtable Base with Records
  • PART 3 – Determine the API URL and API Key
  • PART 4 – Create a Voiceflow Test Project
  • PART 5 – Test using the Amazon Test Simulator

PART 1 – Create an Airtable Workspace and Base

For our tutorial demo, let’s imagine the business requirement is to have Alexa recite quotes, the source of the quotes (ex. A manuscript name, a speech, a newpaper article, etc.), and a location where the quotation was either spoken or published (ex. Where the speech occurred, etc.).

In your Airtable account access your dashboard. Notice that you have a default Workspace entitled “My First Workspace.”

You can create a designated workspace for your Voiceflow projects to help keep them organized. This step is optional.

Click on “+ Add a workspace” in the left column, and add a new workspace with a name of your choosing.

In my case, I happened to already have a “Voiceflow” workspace configured, and also an existing “base” (a “base” is Airtable’s shorthand for a database).

Click on the “Add a base” button to begin creating our database.

A dropdown will open. Select “Start from scratch.”

A window will open where you can name your base. For our tutorial demo I named it “Demo One’. After entering the name, press enter to close the window.

You now have a base named “Demo One”, and has a nice icon with “De” to help identify it.

Click on your new Demo One base, to open the database table. Feel free to click around a bit on the colorful icons in the lower right corner, and familiarize yourself with some of the options along the top.

As you can see in the upper left part of the grid, the default table name is “Table 1.” Let change this to “Quotes 1” for our demo.

Twirl open the small upside down triangle next to “Table 1” to open the following pulldown menu.

Select “Rename table” from the pulldown menu. Edit and rename the tab to read “Quotes.”

New table named “Quotes”, which is a part of the base named “Demo One”

Let’s review the business requirement, which is to have Alexa recite a quote, the source of the quote (ex. A manuscript name, a speech, a newpaper article, etc.), and a location (ex. Where the speech occurred, etc.).

To meet this business requirement, the three fields will be named “Quote,” “Source,” and “Location.”

As such, the design for this tutorial is to have a table with three fields and three rows of data. 

Let’s proceed to change the name of the first field (reminder: “fields” are conceptually similar to columns in spreadsheets).

Twirl open the little upside down triangle just to the left of “Name” in the first column. A pulldown menu will appear.

Select “Rename field” from the pulldown.

Option to rename a field

In the small window that opened, change re-name the field “Quote.” Also notice two things.

The first field is the “primary field.”  This is a unique identifier of the record (row), and must be unique among all the rows. In other words, in the first field (column), the value for each row must be different.  This is how the base keeps track of the various records.

If the concept of a “Primary Field” or “Primary Key” is new to you, the following Airtable reference page provides additional information.  It is an important concept to understand when designing Airtable bases for your Voiceflow projects:

The primary field

Second, notice that the “field type” is “A Single line text” in the light blue box. This is an appropriate data type for a quote. “Long text” is also a good option for longer text. If you twirl open the field type, you will see a variety of other types of data that can be stored.

The following Airtable reference page describes the various field types:

Guide to the basic field types

After you finish editing and renaming the first field, your demo Airtable should look like this:

Let’s change the name of the second field from “Notes” to “Source.”

Twirl open the pulldown for the field name (column header).

Select “Rename field.”

Here, we will change the default name from “Notes” to “Source,” but we also want to change the default field type from “Long text” to “Single line text” (“Long text” is also suitable when working with lengthier text).

First, change the name:

Then, twirl open the light blue box to see the field types:

Change from “Long text” and Select “Single line text.”

Click out of the box. At this point, the first two fields have been renamed to “Quote” and “Source.” The base should now look like this.

To complete our base, re-name the third field from “Attachments” to “Location,” and change the field type to “Single line text.” After completing these changes, your table should look like this:

Congratulations, your test demo Airtable base is now configured, and is ready to be populated with some data!

PART 2 – Populate the Airtable Base with Records

In Part 1 we configured an Airtable “base” (aka a database). The next step is to add records with quotations and interrelated information (the quote’s source, and where the quote occurred or was published).

There are numerous ways to populate the table. For example, the data can be imported from a spreadsheet.

For our demo, we are going to manually type in our records. There are only going to be three rows with three columns of test data for this tutorial.

In the table, manually type in the following test values directly into the three fields for the first row:

For the second row, let’s do something a little different. In the Second row, first field, notice the small diagonal icon. This is an expansion option for the field.

Click on the expansion icon to open up the following window for the field:

Type in the values for the second row for each of the three fields. After you finish typing in the value for the third field, do not close the window yet.

After you finish typing in the value for the third field, notice the small down-arrow icon in the upper left portion of the window.

Click on it. This will advance the window and enable you to easily enter the values for the third row. The small up and down arrows enable you to navigate among each row.

Enter the values for the third row. Once you are finished, click on the small X in the upper right corner of the window.

Upon returning to the grid view of the base, it should now look like this:

Congratulations, your test demo Airtable base is now populated with three records, with three values each! The next step is to locate and identify the API URL and the API Key.

PART 3 – Determine the API URL and API Key

An API URL is available for use to access records in our table via Voiceflow projects. In addition, Airtable requires the use of a secure API Key. When configuring the API Block in Voiceflow we will use both of these pieces of information.

Currently, this is what our Airtable looks like.

In the upper right corner of the screen, there is a HELP button (and a little circle with a question mark in it). Click one of these.

A pulldown will open up. In the pulldown, notice the selection for “<>API documentation.” Select this option.

A nice feature is that Airtable provides custom-configured API documentation for each table. As you recall, we named our table “Demo One.” As such, the API Documentation is conveniently named “Airtable API for ‘Demo One'”.

Review the menu options in the upper left panel. Currently we are in the “INTRODUCTION” section.

Click on the selection for “QUOTES TABLE.” Be aware that these API documents are customized, and that “Quotes” is the name of our base. Upon clicking QUOTES TABLE, a submenu will open up.

In the submenu, click on the selection for “List records.” In this screen, a lot of information is provided in the middle part of the screen regarding the fields and how they work as parameters.

Let’s focus on a couple key pieces of information in the EXAMPLE REQUEST section on the right half of the screen:

  • The “curl” tab in the upper left corner is pre-selected by default. This page provides the URL we are going to use.
  • The first two rows identify the https request URL we are going to use.
  • The third row begins with a blue “H” (which stands for “Header”). This row identifies the API authorization which will be used in the API Request. Initially, a part of it will display as “YOUR_API_KEY.” This will be replaced by your personal API Key as we proceed with the configuration. This bit of information is strongly encouraged by Airtable to be kept private.
  • If you review the tree structure in the EXAMPLE RESPONSE you will see our data.
  • Some key terms to note are “records” and “fields.”  These will be used when configuring our Voiceflow API Block, as these provide a path to the data within the tree structure.
  • Also note our three field names, “Location,” “Quote,” and “Source.” These will also be included in the API response statements.
  • To summarize, these details will be used later when configuring the API Block for the variable assignments our Voiceflow test project.

If you look in the upper right corner of the screen, you will notice a checkbox for “show API key.” Initially this is unchecked by default.

Your personal API key will be needed to configure the header portion of your API block in Voiceflow. This is what provides authorization for your Alexa skill to access your tables. There are two ways to obtain your API Response Key.

  • One way is to go back to your personal account in Airtable and plan to copy/paste it from there. In those screens you also have the option to regenerate your API key, if you feel it is necessary.
  • The second way is to click the checkbox. For this tutorial, this is left unchecked, however you may want to go ahead and check the checkbox so that you will have your API Key available for configuration of the API block in your Voiceflow project.

Let’s take a closer look at the URL. This will need to be copied and pasted from here, to your Voiceflow API Block configuration. The Authorization will be needed as well.

To summarize, what you need to copy and paste are these two items from this screen. Again, the YOUR_API_KEY portion for the authorization will be updated to reflect your actual API Key:

URL:

https://api.airtable.com/v0/appMv0orckRD6BMOa/Quotes?maxRecords=3&view=Grid%20view

NOTE: In the above URL, the maxRecords is set to 3, which matches the number of records we plan to retrieve for our test. You will need to double check and adjust this value for your other projects.

HEADER:
Authorization: Bearer YOUR_API_KEY

You can either keep the API documentation page open, for direct copying and pasting these two statements into your Voiceflow project, or you can copy and paste these into your design document.

Congratulations, we now have our base ready and the API information we need! We are ready to proceed and create a test Voiceflow project for accessing your Airtable information.

PART 4 – Create a Voiceflow Test Project

Let’s proceed to create a very simple project and practice integrating an Airtable base as your datasource. This demo skill will be uploaded to Alexa in the Amazon Developer Console for testing our results, but will not be published.

First log into your account.

Voiceflow

In your project dashboard, you will see your available projects.

Click the “New Project” button.

A preliminary project window will open, where you can enter your skill name.

Enter your skill name in the project name window

In the project name window, enter your skill name. For this demo project, we named it “airtable demo three.” This will also be your invocation name when testing. The letters should be all lowercase.

The English (USA) Language/Region is pre-selected by default. You can optionally change this to a different Language/Region, depending on where you are located and how your Amazon Developer account is configured. To see the options, hit the publishing button marked by the rocket-ship icon in the top right and select your languages.

The image below is what the default Voiceflow project canvas looks like for a new project.

The default template on Voiceflow plays a short message and shows off some of the blocks. To delete all of the blocks at once, you can hold shift, then click and drag to select all of the blocks at once.

Let’s begin adding the API block to the Start Block. This is what we will use to connect the Voiceflow project to the Airtable and retrieve values from the Airtable into variables.

Let's open up our blocks menu on the far left by clicking the blocks icon. You may already have the blocks menu open by default:

Go to the API block in the blocks menu, and click & hold to drag the block onto the canvas:

The API block's menu will open up on the left, and you can see there are quite a few fields. Don't worry, we'll go through them all.

Notice the GET selection should already be pre-selected by default.

Enter a name for the API Block. For our demo, we named it “GetQuotes.” You can name blocks through selecting the block in the block menu:

The final result looks like this. Be sure to connect up your two blocks.

Next we are going to copy and paste the API URL for your Airtable into the following field, where it says “URL Endpoint"

Copy and paste the API URL from the first two rows of your EXAMPLE RESPONSE in your Airtable API documentation. The URL for this tutorial’s demo is:

https://api.airtable.com/v0/appMv0orckRD6BMOa/Quotes?maxRecords=3&view=Grid%20view 

However yours will be different for your project. Also you will most likely need to adjust the maxRecords parameter from 3 to another number which matches the number of records in the other skills you make.

Completed looks like this:

Airtable requires the use of an authorization key. In the Voiceflow API block, we will be populating two fields to accomplish this.

In the API block menu, you need to add the Headers. Click on 'Add Pair' to add a header pairing.

Once the header fields are open, you should see two fields. One for the 'Key' and one for the 'value'.

In the first field where it says “key” enter “Authorization.”

For the second field named VALUE, we are going to add the URL for the Airtable API.  Where the field says “Enter value or {variable}.” copy and paste your API Authorization from the third row of your EXAMPLE RESPONSE in your Airtable API documentation.

The second field in the Header authorization should be similar to this, except your personal API Key will be substituted for “YOUR_API_KEY”:

Bearer YOUR_API_KEY

The two fields for the “Headers” section of the API Block should now look similar to this, except with your actual personal API Key:

Header fields populated with the required Airtable authorizations

Populating the header values is now complete. The next step will be to create variables and populate them with the values coming from the Airtable.

Let’s continue configuring the API Block. In this next section we are going to create three API response statements (object path mappings) and assign them to three new variables. When executed, these will retrieve the Quote, Source and Location values from the first row of the Airtable.

For each variable, we will be populating a pair of fields in the next part of the API block. We do this in the 'Result Variable Mapping' section of the API Block:

In the first field, where it says “Object path,” enter “response.records[0].fields.Quote.” 

Let’s break down the “response.records[0].fields.Quote” object path:

  • If you recall, there are some key terms we noted when reviewing the API Documentation for our Demo One Airtable.
  • These included “records,” “fields”, and the names of the three fields (“Quote,” “Source” and “Location”).
  • These values follow the tree-like structure in the EXAMPLE RESPONSE we reviewed in the Airtable API documentation earlier.
  • These are used to find the specific values in the Airtable base.
  • The numerical “0” programmatically refers to row 1 in the Airtable. Likewise, “1” would refer to row 2, “2” refers to row 3, and so on.
  • In other words, “response.records[0].fields.Quote” is the path that is followed in the tree-like structure to find the value (quote) for the first record.

If you want more examples on writing 'queries' like the above for APIs, we have a tutorial here.

Now that we have identified the path to the value being returned by the API, we need to add and assign a variable to receive it. This variable will then be used later in the Voiceflow project.

To proceed, make sure you have created a variable called QuoteOne by clicking on the variables menu on the far left, and creating a variable.

Back in our API block, we want to set the 'Result Variable Mapping' for our pairing to the variable we just created: QuoteOne.

Variable assignment mapping complete

Congratulations! The first variable assignment is complete. However we have several more to do.

The next step is to create a variable to store the source of the quote in the first row. This value comes from the second field (column) in the first row of our Airtable base.

To proceed, lets add another variable mapping by clicking on "Add Mapping"

To proceed, enter “response.records[0].fields.Source” in the first field where it says “Object path.” Follow the same steps to complete the variable and assignment as we did for the first one.

  • Enter response.records[0].fields.Source for the 'Object Path' of second variable result mapping
  • Create a new variable called 'sourceOne'
  • Select the new variable 'sourceOne' to be used in 'Variable' part of the mapping.

Two variable assignments completed

Add a third variable to store the “Location” value using the same procedure. The mapping is “response.records[0].fields.Location”, and the variable name to use is “locationOne.”

Three variable assignments completed

At this point, we have three variable assignments. quoteOne, sourceOne and locationOne are the three Voiceflow variables to which we have assigned the returned values for the first row in the Airtable.

Here are several design considerations with the API Block:

If we want this particular API Block to retrieve just the first row, we could consider this API Block setup to be complete. However it is also possible to retrieve multiple values from the other rows as well in a API Block.

How you design your API Blocks for your projects will depend on your Alexa skill design and flow. For example, you can retrieve all of your values in one big API Block. Or you could have small API Blocks scattered throughout your Voiceflow project, retrieving only what is needed “just in time,” and depending on what paths are followed based on user responses.

For this test demo, let’s retrieve all three field values for all three rows. Please repeat the steps and add an additional six variables and API Response mappings and assign them to the variables as shown below. You can copy and paste from the following text:

response.records[1].fields.Quote
quoteTwo

response.records[1].fields.Source
sourceTwo

response.records[1].fields.Location
locationTwo

response.records[2].fields.Quote
quoteThree

response.records[2].fields.Source
sourceThree

response.records[2].fields.Location
locationThree

Once the additional variables and mappings are added, the API Block should look similar to this:

Multiple variable assignments completed.

There should be a total of nine new variables and assignments (a quote, source and location for each row, times three rows).

Congratulations! The API Block is now complete!

Testing your API Block

To test your API Block setup with AirTable, simply add a speak block after your API Block to be connected. In the speak block, you can use any of the variables that you have pulled from the API.

Inside our speak block looks like this:

And that's it! Your Alexa will now start the skill from the Start block, move along to the API Block, call the API and capture responses into variables, and finally speak to the user with the newly captured variables in the Speak block.

Try it out for yourself by uploading to Alexa!

Conclusion

During this tutorial we did the following:

  • Created an Airtable base.
  • Added test records to the base consisting of multiple rows and fields.
  • Determined the API URL and API Key for accessing the records.
  • Created a Voiceflow test project and integrated it using an API Block. 

Airtable provides some nice opportunities as a data source for Voiceflow projects and Alexa skills. It is relatively easy to use by non-programmers, and is ideal for team collaboration.

Still have questions? Be sure to post in our Forums to get fast answers!

Did this answer your question?