Build your first app

Learn how to create a simple node.js application that interacts with Envoy.

Time to complete: 20 minutes

This tutorial will cover how to build a simple app using Node.js that displays a custom greeting (Hello World) in the Envoy visitor log when a visitor signs in.


App development involves building and hosting your web app yourself and then registering your app with Envoy. Apps are registered using the Integration Builder.

Apps typically have a few commonalities:

  • Setup steps
  • Events they listen to for
  • Some interaction back to Envoy


When our Hello World app is installed, we'd like the installer to be able to set their desired greetings and salutations. To do this, we'll need to render a dropdown with our greeting options, and allow them to pick one.


In order to greet our guests, we'll need to listen for the "entry sign-in" and "entry sign-out" events, and handle those appropriately.

On entry sign-in, we'll create a personalized greeting for our visitor using the greeting selected during setup as well as the visitor's name.

On entry sign out, we'll do the same, and as an added bonus, we'll add the duration of their visit to the message.

The personalized messages we've created need to find their way back to the visitor somehow. We could send them an email or SMS, but to illustrate the attachment system, we can have those greetings appear in the Envoy dashboard for the receptionist.


To build our app, we're going to create a Node.js application. Note that any language can be used as illustrated in our API reference, but currently only a Node.js SDK is available.

For deployment, we will use GitHub and Heroku for simplicity.


Start by creating a repository on GitHub and cloning it to your local machine. During GitHub repo setup, it's a good idea to select the option for GitHub to automatically include a README and a .gitignore file for Node.js.

git clone

Replace with the clonable URL to your repo.

In the app directory, initialize the Node app.

npm init --yes

A package.json file should have been created. This file describes your application. In this file, add the following key to the JSON:

"engines": {
  "node": "10.x"

Also, we need to point to our start script that we'll create shortly. Replace the scripts portion of package.json with the following:

"scripts": {
  "start": "node index.js"

Later when we deploy to Heroku, this allows it to determine the deployment runtime and what command to run.

Next, if you didn't auto-generate a .gitignore file from GitHub, create one now with the following contents:


Now to install our dependencies. We're going to install Express.js and our Node SDK. Most integrations also talk to external APIs, so you'll often find yourself installing an HTTP request library as well, like axios, superagent, or request (none of these are necessary for this tutorial though).


npm install --save express

Envoy's Node.js SDK

npm install --save @envoy/envoy-integrations-sdk

Once the installation is complete, a package-lock.json file should have been created. This file locks down your installed dependencies to specific versions. Be sure to add this file to git.

Now create an index.js file. This is where we'll write our server script.

The code

In the index.js file, start by including the dependencies we installed.

const express = require('express');
const { middleware, errorMiddleware } = require('@envoy/envoy-integrations-sdk');

Next, initialize Express.js with our middleware.

const app = express();

Setup Routes

Now we can use our app object to define our app's endpoints. Let's start with a route that sends back available options for the "preferred hello" dropdown that we saw in our setup steps screenshot.'/hello-options', (req, res) => {
      label: 'Hello',
      value: 'Hello',
      label: 'Hola',
      value: 'Hola',
      label: 'Aloha',
      value: 'Aloha',

In the above, we're sending back a JSON array of objects where each object has a label and value. Typically these are not the same, but for our case, we'd like what is displayed on the front-end to also be the value we receive later.

Now do something similar for "goodbye".'/goodbye-options', (req, res) => {
      label: 'Goodbye',
      value: 'Goodbye',
      label: 'Adios',
      value: 'Adios',
      label: 'Aloha',
      value: 'Aloha',

Event Handlers

Now we can create our "entry sign-in" worker.'/entry-sign-in', async (req, res) => {
  const envoy = req.envoy; // our middleware adds an "envoy" object to req.
  const job = envoy.job;
  const hello = envoy.meta.config.HELLO;
  const visitor = envoy.payload;
  const visitorName = visitor.attributes['full-name'];
  const message = `${hello} ${visitorName}!`; // our custom greeting
  await job.attach({ label: 'Hello', value: message }); // show in the Envoy dashboard.
  res.send({ hello });

In order to have our message displayed in the Envoy dashboard, we're attaching some data to the job.

Finally, we're sending back a 200 response with some debugging data.

Now for the "entry sign out" worker.'/entry-sign-out', async (req, res) => {
  const envoy = req.envoy; // our middleware adds an "envoy" object to req.
  const job = envoy.job;
  const goodbye = envoy.meta.config.GOODBYE;
  const visitor = envoy.payload;
  const visitorName = visitor.attributes['full-name'];

  const message = `${goodbye} ${visitorName}!`;
  await job.attach({ label: 'Goodbye', value: message });
  res.send({ goodbye });

Wrapping Up

Now that our setup and event endpoints are ready, we can finish our script by making sure we use our errorMiddleware and creating a server on a specific port.


const listener = app.listen(process.env.PORT || 0, () => {
  console.log(`Listening on port ${listener.address().port}`);

Deploying to Heroku

First, be sure to push up all your changes to Github.

Next, log in to Heroku, click on Create New App.

After filling out the name, click Create app.

Next, select GitHub as the deployment method, search for your repo, and click Connect.

Then head to the Settings section and add placeholders for the ENVOY_CLIENT_ID and ENVOY_CLIENT_SECRET environment variables. The Node.js SDK uses these values to authenticate with Envoy.

Finally, scroll to the "Domains and certificates" area, and copy your app's URL.

Register app with Envoy

Now that our code is complete and deployed, we need to let Envoy know about our app. We do that with the Integration Builder.

For an in-depth overview on the builder, see here. For this quickstart tutorial, we are going to start with the create new section.


For all the URL fields below, be sure to replace https://my-heroku-url with the URL you copied from Heroku. Leave the paths to each endpoint the same.


Fill in the basic details about the app.

For the logo, we can use this image


Here's where we define the URLs to each of our workers.

Setup Steps

Create a single setup step that allows the installer to select their preferred greetings.

Click Save Integration.

After saving, your client credentials will be visible. Go back to your placeholder Heroku environment variables that we created earlier and paste in the values for the client ID and secret.

You can now head to the Deploy section of Heroku and scroll to the bottom to manually deploy your app.

Now that your app has the appropriate values, head back to the Integration Builder and check the Yes, display on the Integrations page box and click Save Integration once more.

Your app should now be available in the Envoy dashboard's Integrations page! Go ahead and run through the installation process of your brand new app, and it should be active once complete. Try signing in a visitor to see it in action.


This app is private to your account. Learn how to make your app publicly available to other companies.

Did this page help you?