Application API

A Nexmo application contains the security and configuration information you need to connect to Nexmo endpoints and easily use our products. You use one or more applications to supply a service based on a Nexmo Product. For example, you may create one Voice application to record calls to your support center, and another application for internal conferences.

capi_architecture

Each application has a:

Name Description
msisdn A virtual phone number that you rent from Nexmo and is associated with this application.
type Describes the Nexmo APIs you access for your application. The available types for your application are:
  • voice - for Voice API
private_key You use the private key to generate the JWTs used to authenticate your calls to the Nexmo APIs.
public_key Used by Nexmo to authenticate the JWT in your requests to Nexmo API.
applicationID Used:
  • To identify each application
  • In conjunction with private_key to generate JWTs
webhooks Nexmo sends and retrieves information from your webhook endpoints. Including :
  • answer_url - The webhook endpoint that provides the Nexmo Call Control Object governing a Call or Conference.
  • event_url - Nexmo sends event information asynchronously to this URL when status changes.

Note: by default, all HTTP requests are POST.

You use Application API to create, list, modify and delete applications.

Getting started with applications

To create a Nexmo application:

 
To create a Voice app and send a text-to-speech message:

  1. If you don't already have one, setup a Nexmo account.
  2. Use npm to install and setup the Nexmo CLI:
    #!/bin/bash
    
    #Install the Nexmo CLI:
    sudo npm install nexmo-cli -g
    
      #Nexmo CLI requires NodeJS 4 or above. If you do not have Node,
      #download the installer from https://nodejs.org/en/download/.
    
    #Configure the Nexmo CLI
    nexmo setup <api_key> <api_secret>
    
  3. If you do not have one, rent a virtual number using the Dashboard or the command line:
    > nexmo number:buy 441632960962 --confirm
    Number purchased: 441632960962
    
  4. Create an Application:
    > nexmo app:create "VoiceApplication" http://example.com http://example.com  --keyfile private.key
    Application created: asdasdas-asdd-2344-2344-asdasdasd345
    Private Key saved to: private.key
    
  5. Associate the application_id with your virtual number:
    > nexmo number:update 441632960961 --voice_callback_type app --voice_callback_value asdasdas-asdd-2344-2344-asdasdasd345
    Number updated
    

 

  1. Use the following code examples to create a new Application for Voice API:
    #!/bin/bash
    
    #Create an Application for Voice API.
    
      base_url='https://api.nexmo.com'
      version='/v1'
      action='/applications/?'
      key='API_KEY'
      secret='API_SECRET'
      name='MyFirstApplication'
      type='voice'
      answer_url='https://nexmo-community.github.io/ncco-examples/conference.json'
      event_url='https://example.com/call_status'
    
    #In this example, answer_url points to a static NCCO that creates a Conference.
    
      curl $base_url$version$action \
        -d api_key=$key \
        -d api_secret=$secret \
        -d name=$name \
        -d type=$type \
        -d answer_url=$answer_url \
        -d event_url=$event_url
    
    $base_url = 'https://api.nexmo.com' ;
    $version = '/v1';
    $action = '/applications/?';
    
    //Create an Application for Voice API. 
    $url = $base_url . $version . $action . http_build_query([
        'api_key' =>  'API_KEY',
        'api_secret' => 'API_SECRET',
        'name' => 'MyFirstApplication',
        'type' => 'voice',
        'answer_url' => 'https://nexmo-community.github.io/ncco-examples/conference.json',
        'event_url' => 'https://example.com/call_status'
    ]);
    //In this example, answer_url points to a static NCCO that creates a Conference
    //
    
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_POST, 1);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, array("Accept: application/json", "Content-Length: 0" ));
    curl_setopt($ch, CURLOPT_HEADER, 1);
    $response = curl_exec($ch);
    
    $header_size = curl_getinfo($ch, CURLINFO_HEADER_SIZE);
    $header = substr($response, 0, $header_size);
    $body = substr($response, $header_size);
    
    if (strpos($header, '201')){
        $application = json_decode($body, true);
        if (! isset ($application['type'])){
            echo("Application " . $application['name']
                    . " has an ID of:" . $application['id'] . "\n" ) ;
            echo("  Use the links to navigate. For example: "
                . $base_url
                . $application['_links']['self']['href'] . "\n"  );
        }else {
            echo ( "Error: " . $application['type']
                . " because of " . $application['error_title'] . "\n" );
        }
        foreach($application['voice']['webhooks'] as $webhook)
            echo ( "  " . $webhook['endpoint_type'] . " is " . $webhook['endpoint'] . "\n"  );
    
        echo("  Stock your public and private keys somewhere secure.\n" ) ;
        echo("  You use them to connect to Nexmo endpoints. They are:\n" ) ;
        echo("  " . $application['keys']['public_key'] );
        echo("  " . $application['keys']['private_key'] );
    }
    else {
        $error = json_decode($body, true);
        echo("Your request failed because:\n");
        echo("  " . $error['type'] . "  " . $error['error_title']   );
    }
    
    import urllib
    import urllib2
    import json
    
    base_url = 'https://api.nexmo.com'
    version = '/v1'
    action = '/applications/?'
    
    #Create an Application for Voice API.
    params = {
            'api_key': 'API_KEY',
            'api_secret': 'API_SECRET',
            'name' : 'MyFirstApplication',
            'type' : 'voice',
            'answer_url' : 'https://nexmo-community.github.io/ncco-examples/conference.json',
            'event_url' : 'https://example.com/call_status'
    }
    #In this example, answer_url points to a static NCCO that creates a Conference.
    
    url =  base_url + version + action
    data =  urllib.urlencode(params)
    
    request = urllib2.Request(url, data)
    request.add_header('Accept', 'application/json')
    
    try:
        response = urllib2.urlopen(request)
        data = response.read()
        if response.code == 201:
            application = json.loads(data.decode('utf-8'))
            print "Application " + application['name'] + " has an ID of:" + application['id']
            for webhook in application['voice']['webhooks'] :
                    print "  " + webhook['endpoint_type'] + " is " + webhook['endpoint']
            print "  You use your private key to connect to Nexmo endpoints:"
            print "  " + application['keys']['private_key']
        else:
            print "HTTP Response: " + response.code
            print data
    
    except urllib2.HTTPError as e:
        print e
    
    require "net/http"
    require "uri"
    require "json"
    
    base_url = 'https://api.nexmo.com'
    version = '/v1'
    action = '/applications/?'
    
    #Create an Application for Voice API.
    params = {
      'api_key' =>  'API_KEY',
      'api_secret' => 'API_SECRET',
      'name' => 'MyFirstApplication',
      'type' => 'voice',
      'answer_url' => 'https://nexmo-community.github.io/ncco-examples/conference.json',
      'event_url' => 'https://example.com/status'
    }
    #In this example, answer_url points to a static NCCO that creates a Conference.
    
    uri = URI.parse(base_url + version + action )
    
    response = Net::HTTP.post_form(uri, params)
    
    case response
    when Net::HTTPCreated
      application = JSON.parse(response.body )
      print "Application " + application['name'] + " has an ID of: " + application['id'] + "\n"
      application['voice']['webhooks'].each do |webhook|
          print "  " + webhook['endpoint_type'] + " is " + webhook['endpoint'] + "\n"
      end
      print "  You use your private_key to connect to Nexmo endpoints:\n"
        print "  " + application['keys']['private_key'] + "\n"
    else
      puts response.code + " error sending message"
    end
    
    {
      "id":"A-hypenated-alphanumeric-string-ID",
      "name":"MyFirstApplication",
      "voice":
        {"webhooks":[
          {
            "endpoint_type":"answer_url",
            "endpoint":"https://example.com/ncco",
            "http_method":"POST"
          },
          {
            "endpoint_type":"event_url",
            "endpoint":"https://example.com/call_status",
            "http_method":"POST"
            }
            ]
        },
        "keys":
        {
            "public_key":"-----BEGIN PUBLIC KEY-----
        MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAss4gm1QRIA46Gt597ytP
        e1RcyyaYZFEhfFMTQDW3RlKzxVNVWPDlXYwC6hj/Es9HOX9fWOsWAdVY3QLFO5g1
        TZ+jfkIU0UVMQO5IQdEdiR+gRLSY9ld21fqHew9pyFApMLn8evmkB8TygJx8w7hF
        EIi1Oey7ud719gaZR0LandHa2N0SenseOfHumorzwg2m+TUBqlEp2MtnUxWc1mdm
        H1aJ7MPiL3zb5B0xrGSLrDljzODhovjQbW7W63nDgpe6XvjoXfcqeDw2Pp6HxdBH
        qP/XbMjFev97Y8xmXpmief/qs6UuQrlUzXGWz8HirGpUBvJ7B1ekuSv/nzqJi5E8
        IQIDAQAB
        -----END PUBLIC KEY-----",
            "private_key": "-----BEGIN PRIVATE KEY-----
    MIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQCpAJB4jDbjTWD9
    y71Twc9IV6uFgZ9RtrbiEQjB5pjvgvB+MX7yXya3CYxSGnfGa9FAfJFPR8LeWlbA
    FAikCDmbEzyObgJX1klgyQmQcyGMv3gReuBTIKbZFrGdKwZU56R9P3I3AQiakv4F
    /jMkfMVdvr7qvVBJNtbPi2RD5aqNA34WTZIx2BEGl8/Gykqw4PA2NtBKa0F0Hfzn
    Gxh1DobFpGVWW0YZQU/Z0aZZ/w9H8CChUS1a/MoNwxTVu5T71eLHuQLDNEAGEtjq
    EIi1Oey7ud719gaZR0LandHa2N0SenseOfHumorzwg2m+TUBqlEp2MtnUxWc1mdm
    XWQyyRQFAgMBAAECggEAQjoYY0T/FV/zTEGU9ceTRRQmAPFkz468aCaoueN1txYm
    zCz1RGGJOF0jgeEhYr5Jh+3Iu7qxYJUiPa8cG7ulZ2HIb0Ao5ubwZl8hwlt7oD4/
    /Qmb8AndH3oWesMeADr1nkrdu6s971s1Pc+I6kWJVjbx39Kr5pLuSqw/CABSJmE+
    ltgD/J+rcDuG+E+fvGcUxLsuZGsf5WHFUEV4Tc87Nf248fuIUJicRmpEha5ubard
    2lAw7FOSOW6g+3eurS/Zre6Xn3u0lNTuyGKGfMZW/m6WN1BsFb0erM1YlVhq2SQN
    7jAzpf83M95vD1LAqrmXwgwurY4K2bC6IXdx7UGi2QKBgQDtB0763yQMMidQ6uHG
    RUvNF7A96zkXmr0vQCRqlLZM09KoDk1hvxv6tU+DglrffYQT7JqV1AdhH/HxNco/
    e7H+Vcv9c5EOHU21Kxp+3DntHv5ohqS0XMQZlekEbiXPqkWnuuYlT3XF5iLsyj04
    x0ofTDAixwYNhpL+iw1BvnksmwKBgQC2h2cbpx3CcYbP4ZBwXT2GrqUAyD6Kai17
    E4crrjrUjqCv6EGfkjeLqGFpW2PKtqcGiKyDBxVSeItHXouogYfNvWvb4g4hvFZW
    oZkZWrQvJzcp0KDHn6sYa8TBDEKl2WCwgejg6JxhB+Vafx7Js7HNVCloKEizQKgw
    Jyz0DlK73wKBgQCPRNSjZM8IJCSJj3+qdWZM8F2R/6UBtIFXlyCr33mVVI/HDuYN
    CBPkZUVLizZcUiTMWj5SA9f2B/YYw1edKao7viZP61OpQWMf947LUVgeEJbcHU5e
    ypepk2hGSkHGlPgHWzwTH0VjuigwEkoRELyn0EhkLQJmmIovG2OG8peRswKBgCrw
    NWA68vQ/8p/Kh0j3ljattOE3OgcjrSlL0buD1BEWsFRRRca9BdYTuT6oohQY3bfa
    xQJZ0zlAZDtY0W/FcOYETnA+gGaNQJ5Gi5Z8UPDav85VZs0vEXfAOlvTf4Y2WdmL
    5fWqosbsrZaZWuvGGuibiNYYy+lnJ2mUfa24BNxvAoGBAK5Uc1EmU9PJIc63HX40
    tUBFJckm3fXmb0vl1C+706ppzTO8c5UgiCYl+bkGsRQx4/YaxnkAAwtf0eX+fcuU
    exoWye2L3mPYFLgZCBIoJ0uVJ+fIy4Xoa/KBFkWGCuZb9AEKBKzOJDOEH9G9LaBw
    ou8KHDnGLsGoNTzdHaIkkECb
    -----END PRIVATE KEY-----"
        },
        "_links":
          {"self":
                {"href":"/applications/A-hypenated-alphanumeric-string-ID"}
        }
    }
    
  2. Keep a reference of the following items from the response:
    • application id - you use this id to perform all actions on your application.
    • private_key - the JWTs you use to authenticate your requests to Nexmo API are based on this private key. You should keep this key in a file that is not accessible from the Internet.
  3. If you do not have one, rent a virtual number.
  4. Use the following code examples to make a POST request with Developer API and associate the application_id with your virtual number at msisdn.
    #!/bin/bash
    
    base_url='https://rest.nexmo.com'
    version=''
    action='/number/update'
    application_id='APPLICATION_ID'
    key='API_KEY'
    secret='API_SECRET'
    
    #Change msisdn and country to match your virtual number
    msisdn='441632960960'
    country='GB'
    
    curl -X POST $base_url$version$action \
    -d api_key=$key \
    -d api_secret=$secret \
    -d country=$country \
    -d msisdn=$msisdn \
    -d voiceCallbackType='app' \
    -d voiceCallbackValue=$application_id
    
    
    $base_url = 'https://rest.nexmo.com';
    $action =   '/number/update';
    
    //Change msisdn and country to match your virtual number
    $msisdn = '441632960960'
    $country = 'GB'
    
    $theurl = $base_url . $action . "?" .  http_build_query([
        'api_key' => 'API_KEY',
        'api_secret' => 'API_SECRET',
        'country' => $country,
        'msisdn' => $msisdn,
        'voiceCallbackType' =>  'app',
        'voiceCallbackValue' => 'APPLICATION_ID'
    
    ]);
    
    $ch = curl_init($theurl);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POST, 1);
    curl_setopt($ch, CURLOPT_HTTPHEADER, array("Accept: application/json", "Content-Length: 0"));
    curl_setopt($ch, CURLOPT_HEADER, array('Content-Type: application/x-www-form-urlencoded'));
    curl_setopt($ch, CURLOPT_HEADER, 1);
    $response = curl_exec($ch);
    
    $header_size = curl_getinfo($ch, CURLINFO_HEADER_SIZE);
    $header = substr($response, 0, $header_size);
    $body = substr($response, $header_size);
    echo $header;
    if (strpos($header, '200')){
        echo ("  Success");
    }
    else {
        $error = json_decode($body, true);
        echo("Your request failed because:\n");
        echo("  " . $error['error-code'] . "  " . $error['error-code-label'] . "\n"  );
    }
    
    import urllib
    import urllib2
    import json
    
    base_url = 'https://rest.nexmo.com'
    action = '/number/update'
    
    #Change msisdn and country to match your virtual number
    msisdn = '441632960960'
    country = 'GB'
    
    params = {
        'api_key': 'API_KEY',
        'api_secret': 'API_SECRET',
        'country' : country,
        'msisdn' : msisdn,
        'voiceCallbackType':  'app',
        'voiceCallbackValue': 'APPLICATION_ID'
    }
    
    url =  base_url + action
    data =  urllib.urlencode(params)
    
    request = urllib2.Request(url, urllib.urlencode(params))
    request.add_header('Accept', 'application/json')
    
    try:
        response = urllib2.urlopen(request)
        data = response.read()
        if response.code == 200:
            print "SUCESSS!"
            app = json.loads(data.decode('utf-8'))
            print json.dumps(app, indent=4)
        else:
            print "HTTP Response: " + response.code
            print data
    except urllib2.HTTPError as e:
        print e
    
    require "net/http"
    require "uri"
    require "json"
    
    base_url = 'https://rest.nexmo.com'
    action =    '/number/update'
    
    #Change msisdn and country to match your virtual number
    msisdn = '441632960960'
    country = 'GB'
    
    params = {
        'api_key' => 'API_KEY',
        'api_secret' => 'API_SECRET',
        'country' => country,
        'msisdn' => msisdn,
        'voiceCallbackType' =>  'app',
        'voiceCallbackValue' => 'APPLICATION_ID'
    }
    
    url =  base_url + action + "?"
    
    uri = URI.parse( url )
    post_request = Net::HTTP::Post.new(uri.request_uri)
    post_request.add_field('Content-Type', 'application/x-www-form-urlencoded')
    post_request.add_field('Accept', 'application/json')
    post_request.form_data = params
    
    http = Net::HTTP.new(uri.host, Net::HTTP.https_default_port)
    http.use_ssl = true
    
    response = http.request(post_request)
    
    case response
    when Net::HTTPOK
      print "Success"
    else
      print "Could not update your application"
        print response.body
        print "\n"
    end
    
    {
      "error-code": "200",
      "error-code-label": "success"
    }
    
Previous   Next