Designing

How to design your assistant on Voiceflow.

Integration Steps

An overview of the Steps used to connect external data and functionality into your assistant.

Overview

The collection of Integration Steps available will allow you to send and receive data from external sources, and layer in additional functionality to you project that isn't natively supplied by Voiceflow.

API Step

The API Step allows you to make custom API calls to connect your project with external APIs and data.

The API block consists of several parts:

  • The request type
  • The endpoint
  • Headers, Body and Params
  • Saving to variables
  • Test Request

Request Types Supported

There are 5 standard request types available through the API block.

  • GET - Retrieves information from your data source
  • POST - Creates information in your data source
  • PUT - Completely updates information in your data source
  • PATCH - Partially updates information in your data source
  • DELETE - Deletees information in your data source

Endpoint

The endpoint is the URL that points to your API. Similar to website URL, your endpoint URL is where your requests will be sent to speak with your API.

An example API could look like the following:

<https://api.twitter.com/1.1/search/tweets.json>

Headers, Body and Params

Your API may need additional information in order to give you information. This information can include data like Usenames, Passwords, Authentication tokens, etc. Typically these will be provided by your API provider in their documentation.

Saving to variables

Once you have succesfully made an API call, you will receive back a JSON object. Once you have this, you will likely want to save some of the information you got back onto Voiceflow to speak back to the user, send to another API or compare to something that a user has said. You can do this using the "Transform into Variables section". Simply copy the object path, and paste it into the text box. Then select a variable that you would like to save to.

Test Request

Testing the request will allow you to make sure that your API call is working before moving on in your project. If it succeeds, you will see a message saying "Success". You can click on the copy icon beside portions of the JSON to copy the object path and save it into a variable.

Code Step

The code step allows you to write and execute custom JavaScript (ES6) code within your project. You can access and use external libraries within the step, using the requireFromURL function.

Using project variables in your code

The code step automatically allows for all of your project variables to be used within the code step. To use variables within the code step, simply type the name of the variable.

Success and Failure paths

The code step has two default paths: Success and Failure. The Success path will be followed if your code is successfully ran, and the Failure path will be followed if your code fails to run. If your Code Step is within a turn block, it will not have the Failure path available and your project will end automatically if your code fails to run.

Google Sheets

If you're looking for a quick and easy way to save and retrieve data for your project, you can use the Google Sheets Step as a simplified database.

Actions Available

There are four different types of actions you can take with a connected Google Sheet:

Retrieve Data - pull a specific piece of data from your sheet, and save it as a variable to use in your project

Create Data - add a new row of data to your sheet

Update Data ****- overwrite a set of data in your sheet

Delete Data - remove specific data from your sheet

Authenticating User

You will need to link your Google Account in order to access the sheets you have available. Before you begin your work, be sure to set up the Google Sheet you will be using for your project, including defining all of the headers required in the first row of your spreadsheet.

Selecting a Sheet

Once you have selected the action you wish to take and authenticated your account, you can select the spreadsheet and sheet within it you wish to link to.

Defining Mapping, Values or Settings

You will next need to define the function of the action you wish to take. Depending on the action you selected in the first step, the requirements here will be different:

Mapping Output - here you can select which of your sheets columns will map to which of your project's variables when retrieving data

With Values - here you can identify which variables from your project will be mapped to which columns when the data is created or updated

With Settings - here you can define the range of rows you wish to delete

Testing your Integration

Before using the step, you can test the integration you have configured to ensure that it is working as expected. In the event that your integration fails during testing or in production, you can define an error path using the 'Failure' port on the step on canvas. If the integration should fail, your project will follow that path.

Custom Action

The Custom Action Step is paired with the Voiceflow Dialog Manager SDK and is used to create custom actions that will be performed on Custom Assistants. Each path created on the Custom Action Step creates a trace that is visible in the JSON response served by the Voiceflow Dialog Manager API. This allows you to create custom actions using the Voiceflow SDK that are triggered when this step and its respective paths are invoked.

Designing a Custom Action

The action step allows for adding custom labels and paths to your canvas. This is useful for creating mock actions or paths. Here is an example of using an action step to simulate a payment:

Name: Credit Card Payment

Path 1: Payment Successful

Path 2: Payment Pending

Path 3: Card Denied

Testing a Custom Action

During shared prototyping, the user will always proceed down the default path when they run into the action step. If debug mode is on, the test will stop on the action step and buttons are presented for which path to take.

Developing a Custom Action

For developers using the Dialog Management API, the action step always produces a trace with the action name as type, and action details as payload. If your action name is part of the request config.stopTypes, you can determine which path to take in the next request. Developers can then configure the actual custom action (such as calling stripe to make a credit card payment).

Read more about the Voiceflow Dialog Manager SDK and API here.

Other docs in this section