Skip to content
No description or website provided.
Branch: master
Clone or download
shaunpersad Merge branch 'feature/storage-support'
# Conflicts:
#	lib/request.js
Latest commit a032f89 Apr 25, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.

Envoy Platform NodeJS SDK

This plugin is setup to handle events, routing, and intercept synchronous flows from Envoy.



Get started by following the instructions in the package.

Run npm install to install the necessary packages.

Store local environment variables in .env.local and production environment variables .env.production. Do not commit these files.

Writing Routes

First add your route to envoy-manifest.json and run envoy sync in order to let Envoy know about your new routes. The format of the route json should be as follows:

  "method": "GET", // http method of route
  "path": "hello-world/:name", // rails style route pattern relative to /platform/your-plugin-name
  "handler": "hello-world" // name of route handler

Routes are forwarded from Envoy relative to the url Use routes for serving up important data that might be used by your configuration setup or to provide UX unique to your plugin.

Route Handlers

All route, event, and interception handlers look the same. Each handler is passed an instance of Request and Response.

platform.route('hello-world', function(req, res){
  res.html("<b>Hello World!</b>");


  • req.event_id — uuid for event (handler only, not available on route)
  • req.params — url params or args
  • req.payload — POST or JSON data
  • req.path — full relative path of request (e.g. hello-world/david)
  • req.headers — object of http headers whitelisted in manifest
  • req.user — user object (optional)
  • req.location — location object (see api docs)
  • — company object (see api docs)
  • req.config.user — saved configuration data for the requesting user for this plugin
  • req.config.location — saved configuration data for the requesting location for this plugin
  • — saved configuration data for the requesting company for this plugin
  • req.async — boolean true or false


  • res.header('Content-Type', 'application/json');
  • res.succeed();
  • res.continue(event_id); — use for getting out of an intercepted flow and continuing with Envoy functionality
  • res.json({foo: true});
  • res.html('<b>Hey World!</b>');
  • res.raw('HELLO WORLD');
  • res.file('./path/to/file'); — may not be viable on lambda
  • res.redirect('./relative-url'); — ./relative, /root, or
  • res.error('text');
  •'user|location|company', {foo:'bar'}); — saves data to key value store without requiring additional requests

Async Event Handlers

You can trigger functionality on specific events. For example, if you want to respond to the host_notification event in certain conditions by turning on the fire sprinklers you could to this.

// envoy-manifest.json
  // ... other configuration
  "events_handled" : {
    "host_notification": {
      "with": [] // use for requesting additional data not usually passed
// index.json
// ... other logic
var myBuilding = require('my-building');
var shield = require('shield');
platform.handle('host_notification', function(req, res){
  if( == 'Hulk') {
    shield.request_assistance_from(['Iron Man', 'Thor']);

Synchronous Event Interceptors

You can trigger synchronous functionality on specific events. For example, if you want to display a document for signing before the check-in completes.

// envoy-manifest.json
  // ... other configuration
  "routes": [
  "events_intercepted" : {
    "guest_signin": {
      "with": [] // use for requesting additional data not usually passed
// index.json
// ... other logic
var docusign = require('docusign-api');

platform.intercept('guest_signin', function(req, res){
  docURL = docusign.getDocumentForSigning({callback:'signature-callback/'+req.event_id)});

platform.route('signature-callback', function(req, res){
  if(req.payload.signed) {
  } else {
    res.error("Unable to complete checkin. Invalid signature.");

Environment variables

Environment variable name required for note
DEBUG logger.* added by cli
ENVOY_BASE_URL this.event* added by cli
ENVOY_PLUGIN_KEY this.event* added by cli
E_TWILIO_SID this.sms.*
E_TWILIO_TOKEN this.sms.*
E_TWILIO_NUMBER this.sms.*
OAUTH_<app_id>_CLIENT_ID oauth config
OAUTH_<app_id>_CLIENT_SECRET oauth config
OAUTH_<app_id>_AUTHORIZE_URL oauth config
OAUTH_<app_id>_SITE oauth config
OAUTH_<app_id>_REDIRECT_HOST oauth config
OAUTH_<app_id>_TOKEN_URL oauth config
OAUTH_<app_id>_SCOPE oauth config
------------------------------ -------------- --------------
You can’t perform that action at this time.