Conversion API

You use the Conversion API to tell Nexmo about the reliability of your 2FA communication. Adding conversion data means that Nexmo delivers messages faster and more reliably.

Conversion data 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 used to deliver SMS and Voice. Using Adaptive Routing(™) Nexmo actively reroutes messages through different carrier routes and ensures optimum delivery for your messages. The route choice is made using millions of real-time conversion data points.

Message delivery indicators are:

  • Delivery receipts - 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 mins using data points from the previous 15mins.

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 integrated seamlessly into Verify for fast and reliable delivery of your content.

The following figure shows the Conversion API workflow:

workflow_conversion_api

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:
  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 for Adaptive Routing.
    <?php
    //You use the information you recieved in response from a request to SMS API or Call API.
      $url = 'https://api.nexmo.com/conversions/sms?' . http_build_query([
              'api_key' => 'API_KEY',
              'api_secret' => 'API_SECRET',
              'message-id'=> message-id,
              'timestamp'=> yyyy-MM-dd HH:mm:ss,
              'delivered'=> true_or_false
          ]);
    
      $ch = curl_init($url);
      curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
      curl_setopt($ch, CURLOPT_HEADER, 1);
      $response = curl_exec($ch);
      $header_size = curl_getinfo($ch, CURLINFO_HEADER_SIZE);
      $header = substr($response, 0, $header_size);
      if (strpos($header, '201')){
        echo ("Success");
      }
    }
    
    import urllib
    
    #You use the information you recieved in response from a request to SMS API or Call API.
    
    params = {
        'api_key': 'API_KEY',
        'api_secret': 'API_SECRET',
        'message-id': THE_ID_FROM_THE_RESPONSE,
        'timestamp': IN_UTC_yyyy-MM-dd HH:mm:ss,
        'delivered': true_or_false
    }
    
    url = 'https://api.nexmo.com/conversions/sms?' + urllib.urlencode(params)
    
    response = urllib.urlopen(url)
    print response.read()
    
    require "net/http"
    require "uri"
    
    #You use the information you recieved in response from a request to SMS API or Call API.
    
    uri = URI.parse("https://api.nexmo.com/conversions/sms?")
    params = {
        "api_key" => 'API_KEY',
        "api_secret" => 'API_SECRET',
        "message-id" => THE_ID_FROM_THE_RESPONSE,
        "timestamp" => IN_UTC_yyyy-MM-dd HH:mm:ss,
        "delivered" => true_or_false
    }
    
    response = Net::HTTP.post_form(uri, params)
    
    puts response.body
    
    //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 telling you if your conversion data was received by Nexmo.
    <?php
      //Check if the conversion data was delivered successfully
      $header_size = curl_getinfo($ch, CURLINFO_HEADER_SIZE);
      $header = substr($response, 0, $header_size);
      if (strpos($header, '201')){
        echo ("Success");
      }
    
    if response.code == 200 :
        print "success"
    
    if response.kind_of? Net::HTTPOK
      p "Success " 
    
    
      if (!error && response.statusCode == 200) {
        console.log("success") ;
      }
    })
    
Previous   Next