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. Possible values: voice, messages, rtc
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