Welcome to Nexmo Developer

We are improving our Documentation, API references, learning resources & tooling to help you more effectively use our services. We want to help you find everything you need to integrate Nexmo APIs into your code.

As we start this transition, we’d love to hear from you with thoughts & suggestions. If you’ve got something, positive or negative, to tell us, please tell us using the feedback tool at the bottom of each guide or file an issue on GitHub. - Nexmo

Overview

The Conversion API allows you to tell Nexmo about the reliability of your 2FA communications. Sending conversion data back to us means that Nexmo can deliver messages faster and more reliably.

The conversion data you send us is confidential: Nexmo does not share it with third parties.

In order to identify the carriers who provide the best performance, Nexmo continually tests the routes we use to deliver SMS and voice calls. Using Adaptive Routing™, Nexmo actively reroutes messages through different carrier routes and ensures faster and more reliable delivery for your messages. The route choice is made using millions of real-time conversion data points.

Message delivery indicators are:

  • Delivery receipts (DLRs) - in most instances DLRs are indicative of handset delivery. Unfortunately, delivery receipts are not always a reliable measurement of SMS reception. Nexmo uses conversion data as our main quality measurement.
  • Conversion data - by continuously sending a small amount of traffic to carriers, we see which route is performing best at a point in time and automatically reroute accordingly. This analysis is carried out every 5 minutes using data points from the previous 15 minutes.

When you are implementing Conversion API you must differentiate between your 2FA traffic and other messages. For example, Event Based Alerts or marketing messages. To do this, use one api_key to authenticate requests to Conversation API for 2FA traffic, and a different api_key for everything else.

Note: to rapidly integrate 2FA into your app, use Verify API or Verify SDK  . The Conversion API is already integrated into Verify for fast and reliable delivery of your content.

The following figure shows the Conversion API workflow:

Conversion API workflow

Access to the Conversion API is not enabled by default when you create your Nexmo account. To use Conversion API, you must first request access in an email to support@nexmo.com.

Once you have access, to use Conversion API:

  1. Start a 2FA workflow using either:

    1. SMS API
    2. Text-to-Speech Prompt API 
  2. Nexmo sends a text or voice message to your user.

  3. Your user replies to your message or verification request.

  4. As soon as possible, send a Conversion API request with information about the Call or Text-To-Speech identified by message-id. Nexmo uses your conversion data and internal information about message-id to help improve our routing of messages in the future.

    //You use the information you recieved in response from a request to SMS API or Call API.
    
    var https = require('https');
    
    var data = JSON.stringify({
     api_key: 'API_KEY',
     api_secret: 'API_SECRET',
     message-id: message-id,
     timestamp: yyyy-MM-dd HH:mm:ss,
     delivered: true_or_false
    });
    
    var options = {
     host: 'api.nexmo.com',
     path: '/conversions/sms',
     port: 443,
     method: 'POST'
    };
    
    var req = https.request(options);
    
    req.write(data);
    req.end();
    
    var responseData = '';
    req.on('response', function(res){
     res.on('data', function(chunk){
       responseData += chunk;
     });
    
    });
    

  5. Check the Response to see if we successfully received your conversion data.

    if (!error && response.statusCode == 200) {
      console.log("success") ;
    }