google-runtime is an http webhook service that handles Google Assistant/Dialogflow requests and generates a response. It manages the state of the user based on the project made on the Voiceflow Creator tool. It can be run independently from Voiceflow.

This is the same service that hosts all Google Actions and Dialogflow projects created on Voiceflow. This includes serving production apps on and handling millions of requests.

export your voiceflow project from the creator tool. Each time you update your project you will need to export again. You can find the export option here:

It should save a .vfr (voiceflow runtime) JSON file from your browser that would be named similar to this: VF-Project-nPDdD6qZJ9.vfr

fork/clone voiceflow/google-runtime to your local machine. Ensure nodejs, npm, and yarn are set up on your local machine. Run yarn to install all dependencies.

Add your VF-Project JSON file under projects/

Also add the following file to the local repository:

.env.local

SESSIONS_SOURCE='local'
PROJECT_SOURCE='[YOUR EXPORTED PROJECT FILE HERE (i.e. VF-Project-nPDdD6qZJ9.json)]'

AWS_REGION='localhost'

PORT=4000
SESSIONS_DYNAMO_TABLE="none"
VF_DATA_ENDPOINT="none"

INTEGRATIONS_HANDLER_ENDPOINT="none"

LOG_LEVEL="warn"
MIDDLEWARE_VERBOSITY="debug"

ADMIN_SERVER_DATA_API_TOKEN="none"

PG_USERNAME='PG_USERNAME'
PG_HOST='PG_HOST'
PG_DBNAME='PG_DBNAME'
PG_PASSWORD='PG_PASSWORD'
PG_PORT='PG_PORT'

Install a localhost tunnel tool such as ngrok, localtunnel, or bespoken proxy. This will allow you expose a localhost endpoint on the internet for Google Assistant to hit. For the purposes of this guide, we will implement ngrok

Run your local instance of voiceflow/google-runtime with

yarn start:local

This will now be running on port 4000 of localhost. Expose this with

ngrok http 4000

In your shell you will see a link similar to this - https://e9g1335dd0ac.ngrok.io, note this down. Ensure you copy the https:// version instead of http://

On https://console.actions.google.com/ find the action uploaded by the creator tool, click into it. On the left bar, select "Endpoint", it should say something similar to https://google.voiceflow.app/webhook/[versionID]. Replace the https://google.voiceflow.app portion with your own ngrok endpoint. It should end up looking something like this:

(make sure that it ends with /webhook/[versionID])

You should now be able to test your action using the Actions Contol Test tool or on an actual Google Assistant device and see that it is executing on your local machine.

with this .env.local configuration, the code, google, zapier, and API blocks will not work

every time you make changes on Voiceflow that you want to run, you will need to export again, move the project file to /projects and update PROJECT_SOURCE in .env.local and restart voiceflow/google-runtime - finally update the endpoint again on ADC (it will be overwritten by https://google.voiceflow.app again)