Getting Started with Node.js¶
This tutorial will have you deploying a Node.js app for use on SMS and Web channels in minutes.
The tutorial assumes that you have a free or paid ONEm account, and that you have the following prerequisites installed locally:
Set up on localhost¶
To start with, we will be running all commands locally on your own PC. Your app will initially be hosted there for local development, then later you will learn how to host your app using a cloud provider such as Heroku for use on production.
Before you continue, check that you have the prerequisites installed properly. Type each command below and make sure it displays the version you have installed. Your versions might differ from the example. If an error is returned, go back check the installation before continuing.
This tutorial will work for any version of Node greater than 8 - check that it’s there:
npm is installed with Node, so check that it’s there. If you don’t have it, install a more recent version of Node:
We will use ngrok to provide a secure tunnel between your app running on localhost and the ONEm servers. Check it's installed:
Prepare the app¶
In this step, you will prepare a simple Hello World application. To clone a local version of the sample application, execute the following command in your local command shell or terminal:
You now have a functioning git repository that contains the Hello World application as well as a
package.json file, which is used by npm (Node’s dependency manager).
Install the package dependencies with npm:
Configure the app¶
The Hello World example application listens on the HTTP port defined by the environment variable
PORT or 8080 by default. You can change the port by creating a
.env file in your app's root directory and specifying the desired port value, like this:
Callbacks triggered by the ONEm platform contain a jwt token in the authorzation header. The jwt token carries the unique identity of the ONEm user so that your app can differentiate requests from different users. In order to verify jwt tokens that are sent by the ONEm platform, the token secret should be configured in two places:
- Your local environment
- In the developer portal (see "Register the App in the Developer Portal" below).
Configure the secret in the
.env file, for example:
Run the app¶
Start the app with:
You should see output similar to the following in the console:
Now run ngrok to create a secure tunnel to your local computer so that your app is visible to the ONEm servers.
ngrok will launch a continuous display to the console. Make a note of the HTTP or HTTPS forwarding address. In the example below the address is
Navigate to the forwarding link in your browser and you should see a Hello World greeting.
The Hello World example app expects to receive HTTP requests as users perform certain actions. We call these callback notifications. The Hello World example app expects to receive callback notifications on the base path:
/api. The ONEm platform will need to be configured with the fully qualified URL of this endpoint, including the base path. In our example above, the callback url would be
http://6e3f3fce.ngrok.io/api. We shall configure this callback url in the next step.
Make a note of your callback url and token secret, you will need them in the next step.
Register the app in the Developer Portal¶
If you have not already done so, sign-up for a free ONEm developer account.
Register your app on the ONEm Developer Portal by selecting the Create app option. You will need to provide:
- A short description of your app
- The app category, just select "Business"
- The callback url you obtained from the previous step
- The value of token secret that you provided in your environment settings
Make sure the details are saved correctly in the portal.
Don't worry about the other app details at this stage, we will use them later in the advanced tutorials.
Test the app¶
In the ONEm Developer Portal, select the Test Client tab and register your mobile number. Then in the input field, enter
# followed by your app's name, for example
#HELLO.WORLD if your app is called hello.world.
If you have completed everything correctly, the ONEm system should respond with a menu, similar to the below:
1 2 3 4 5
If you see the above, congratulations, you have successfully installed your first app. Give yourself a pat on the back and then head over to the advanced tutorials to get to know ONEm better.
If you don't see the above done worry, go back and check that each step has been followed properly and your program will soon be up and running.