Getting Started with Nexmo on Bluemix

Share this post:

Nexmo, The Vonage API Platform, provides tools for voice, messaging and phone verification, enabling you to embed programmable communications into mobile apps, websites and business systems. Nexmo APIs include SMS text messaging, two-factor authentication, voice, chat, and social media connect.Nexmo logo

To get started with Nexmo APIs on Bluemix:

  1. Register for the 30-day free trial of Bluemix
  2. If you don’t have a Nexmo account, sign up for one.
  3. Login to Nexmo Dashboard. Scroll to the API Settings section to get your API credentials. You will need the API Key and API Secret for this tutorial.Screen shot of Nexmo API Settings

This step-by-step instruction uses Node.js, so you’ll need to install it on your machine. Once you are ready, let’s get started!

Creating a New Application

  1. Go to your Bluemix Dashboard, and click the Create App button (see below):Screen shot of Create a Bluemix app window
  2. Next, scroll down to Cloud Foundry Apps, and choose SDK for Node.js (see below):Cloud Foundry Apps - SDK for Node.js
  3. Then, give your new application a unique name. In this tutorial, you are going to build a very simple app that just sends an SMS message to your phone number, so let’s name it something like “send-SMS”. Then click Create (as shown below):Create a Cloud Foundry app

Now, you’ll go back to the dashboard. You should see some progress indicators that shows you the new application has been created.

Using Nexmo with the New Application

As was mentioned, you are going to send a simple SMS message.

  1. Click Catalog at the top menu bar (see image below):Cloud Foudry apps - Go to Catalog
  2. At the catalog, search Nexmo under Application Services, then click it:Add Nexmo from the Bluemix Catalog
  3. At the next screen, fill out your Nexmo API Key and API Secret:Nexmo API Key and API Secret
  4. Click Create, then press Create Connection at the next screen to connect it with your new application.

Downloading Your Template Files

After you connected the service to your “send-sms” application, click the app, then Getting Started from the side menu, then click “Download the Sample Code” link to get the zip file to your computer. Now unzip it. The folder should contain the template code files. Now you are ready to move on!

Using the Cloud Foundry Command Line interface

To download, modify, and redeploy your Cloud Foundry applications and service instances, you need to download and install the Cloud Foundry command line interface (CLI).

  1. After the installation, use the cf command to login and connect to the Bluemix environment:
    $ cf api

    Or use the API endpoint for your region, (United Kingdom) and (Sydney).

  2. Then login:
    $ cf login

Now you got your Bluemix app set up, so you can get started creating your Node.js application.

Setting up Your Nexmo Phone Number

In this tutorial, we are going to create a very basic app that sends an SMS message from your Nexmo phone number to your mobile phone number.

You can get your own number by going to your Nexmo dashboard and click Numbers from the top menu bar. Although you can purchase any number with a country code of your choice, to avoid the international fee, you should choose the same country code as your mobile phone number where you will be sending the SMS message.Nexmo Buy numbers window

Using the Nexmo REST API Client for Node.js

Now, let’s code! Make sure that node.js is installed on your machine to start coding.

Take a look at the project folder that you previously downloaded from your Bluemix dashboard. It should contain files like this:

├── app.js
├── manifest.yml
├── package.json
└── public
├── images
├── index.html
└── stylesheets

On terminal, cd to the project root, then use the npm command to install dependencies:

$ npm install

Then install Nexmo Node.js client library:

$ npm install nexmo --save

This will add nexmo as the dependencies in your package.json file automatically. Also, check your manifest.yml file, which is used by Bluemix for the deployment. It should look like this:

- path: .
- Nexmo-yl
name: send-sms
host: send-sms

For the service name, you have an automatically generated one for your application. It usually looks like this, nexmo-, and two random characters, such as nexmo-yl. You will need your service name at the next step.

Now, open the app.js file. At the end of the code template, assign your Nexmo API credentials. You can access your Nexmo credentials within the VCAP_SERVICES environment variable with cfenv that parses Cloud Foundry-provided environment variables:

// The next two lines have been declared already in the template
const cfenv = require('cfenv');
const appEnv = cfenv.getAppEnv();

// Copy and paste these lines to your app.js
const nexmoApiKey = appEnv.getServiceCreds('Nexmo-j1')['api_key'];
const nexmoApiSecret = appEnv.getServiceCreds('Nexmo-j1')['api_secret'];

Again, the name must match your generated service name. To find out all the VCAP_SERVICES info, use cf env [APP_NAME] command on terminal.

Now, initialize a Nexmo instance with the credentials:

const Nexmo = require('nexmo');

const nexmo = new Nexmo({
apiKey: nexmoApiKey,
apiSecret: nexmoApiSecret


Sending SMS Messages with Node.js

Now, let’s send a SMS message from your Nexmo virtual number to your real mobile phone! To send a message, use the nexmo.sms.sendSms function and pass your virtual number (YOUR_VIRTUAL_NUMBER) you are sending the message from, a recipient number, and the message to be sent. Also, you can pass optional params and a callback.

For this exercise, let’s simply hard-code your mobile real phone number (which should start with a country code, e.g. “15105551234”) and a message to try the API:

YOUR_VIRTUAL_NUMBER, '15105551234', 'yo',
(err, responseData) => {
if (err) {
} else {

Now, let’s deploy this app to Bluemix.

Deploying Your Application

To deploy your application, you will be using the Cloud Foundry CLI again. You can push your code with cf push command:

$ cf push

Once your application is deployed to Bluemix and run correctly, Nexmo will send the message to your phone. The time of the actual delivery depends on your mobile phone carrier, so it can be instant, or it might take a few seconds.Nexmo SMS Android example

While this example is a simple SMS application,  it should provide you with a good idea of how to use the Nexmo SMS API to build better applications! To create something more practical using the Nexmo APIs, such as an app to make and receive voice calls or setting up two-factor authentications, visit the Nexmo Tutorial Blog.

More How-tos stories
May 7, 2019

We’ve Moved! The IBM Cloud Blog Has a New URL

In an effort better integrate the IBM Cloud Blog with the IBM Cloud web experience, we have migrated the blog to a new URL:

Continue reading

May 6, 2019

Use IBM Cloud Certificate Manager to Obtain Let’s Encrypt TLS Certificates for Your Public Domains

IBM Cloud Certificate Manager now lets you obtain TLS certificates signed by Let’s Encrypt. Let’s Encrypt is an automated, ACME-protocol-based CA that issues free certificates valid for 90 days.

Continue reading

May 6, 2019

Are You Ready for SAP S/4HANA Running on Cloud?

Our clients tell us SAP applications are central to their success and strategy for cloud, with a deadline to refresh the business processes and move to SAP S/4HANA by 2025. Now is the time to assess, plan and execute the journey to cloud and SAP S/4HANA

Continue reading