zscgeek/vf-general-runtime

Runtime for executing voiceflow projects and conversational state management across different platforms

general-runtime

general-runtime is an http webhook service that handles voiceflow prototype requests and generates a response. It manages the state of the user based on the programs (flows) made on the Voiceflow Creator tool. This can be hosted independently from Voiceflow.

This is the same service that powers the Voiceflow test tool and Voiceflow DM API. This includes supporting production apps and handling millions of requests.

Documentation

For a high level understanding of what the service is doing, reference "What is the Voiceflow API and how do you use it?".

To interact with your general-runtime server, reference the Voiceflow DM API. Instead of the default https://general-runtime.voiceflow.com, use your own local or remote endpoint.

Setup (Local)

run yarn in command line to install all dependencies.

For the isolated-vm dependency, there are additional steps to install here

Add the following file to the local repository:

.env.local

PORT=4000
LOG_LEVEL="info"
MIDDLEWARE_VERBOSITY="none"

SESSIONS_SOURCE='local'
GENERAL_SERVICE_ENDPOINT='https://general-service.voiceflow.com'

# use local vfr file under /projects
PROJECT_SOURCE='[VFFILE.vfr]'

For more info on Environment Variables

Use yarn start:local to run the development version.

For the production version, run yarn build followed by yarn start (this checks against .env.production instead of .env.local)

Notable Code Locations

Context Handlers (documentation)- handlers for processing request
lib/services/runtime/handlers - handlers for all the various nodes and defining their behavior
runtime/lib/Runtime/cycleStack - iterator and execution of flows
runtime/lib/Runtime/cycleHandler - iterator and execution of individual nodes

API Documentation (Open API)

Documentation for all API Endpoints on this service. It is critical to make sure all OpenAPI docs are up to date:

https://github.com/voiceflow/general-runtime/tree/master/backend/docs/openapi.yaml

Whenever any of the paths change, or new ones get added, or if any of the behaviors documented change, be sure to update the Open API doc. Recommend to use an editor like Swagger Editor or Stoplight to help construct the YAML file, and then fine tune things on local.

Local Setup

Run npm i -g redoc-cli to install as command.

While on the root of this repository, run

redoc-cli serve backend/docs/openapi.yaml --ssr --watch

to see it locally - note: this will not load the local CSS file.

If your browser autoresolves http://localhost to https://localhost, you might want to open the local link in incognito or a different browser.