Application Overview

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.

#{alt_text}

Structure

Each application has the following

Name Description
msisdn A virtual phone number that you rent from Nexmo and is associated with this application.
type Describes the Nexmo API you access for your application currently only voice may be used 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 & used 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 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.

    $ npm install nexmo-cli -g
    $ 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 447700900000 --confirm
    
  4. Create an Application:

    $ nexmo app:create "VoiceApplication" http://example.com/webhooks/answer http://example.com/webhooks/event  --keyfile private.key
    
  5. Associate the application_id with your virtual number.

    $ nexmo link:app 447700900000 aaaaaaaa-bbbb-cccc-dddd-0123456789ab
    
  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
    
    <?php
    
    $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 requests
    
    url = 'https://api.nexmo.com/v1/applications'
    data = {
            '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.
    
    resp = requests.post(url, params=data)
    
    try:
        if resp.status_code == 201:
            application = resp.json()
            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: " + resp.status_code
            print resp.json()
    
    except requests.exceptions.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
    
  2. Keep a reference of the following items from the response:

    Key Description
    application id This ID is used to perform all actions on your application.
    private_key The JWTs used 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='447700900000'
    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
    
    <?php
    
    $base_url = 'https://rest.nexmo.com';
    $action =   '/number/update';
    
    //Change msisdn and country to match your virtual number
    $msisdn = '447700900000'
    $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 requests
    
    url = 'https://rest.nexmo.com/number/update'
    
    #Change msisdn and country to match your virtual number
    msisdn = '447700900000'
    country = 'GB'
    
    data = {
        'api_key': 'API_KEY',
        'api_secret': 'API_SECRET',
        'country' : country,
        'msisdn' : msisdn,
        'voiceCallbackType':  'app',
        'voiceCallbackValue': 'APPLICATION_ID'
    }
    
    resp = requests.post(url, params=data)
    
    try:
        if resp.status_code == 200:
            print "SUCESSS!"
            print resp.json()
        else:
            print "HTTP Response: " + resp.status_code
            print resp.json()
    except requests.exceptions.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 = '447700900000'
    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