Nexmo Labs hosts "beta" products, integrations, a small set of projects and experimental features built by Nexmo and our developer community.

Before you get started

Create your Nexmo account, it's free



Voice: Introduction

We have been offering voice capabilities using our Text To Speech API, and we also support outbound and inbound calls via SIP. Up until now we have offered the capability to forward the call to either a phone number or to a SIP end point. We are now adding the capability to initiate a voice call via HTTP and forward an inbound call to a VoiceXML script at a given callback URL.

Call

To make an outbound call.

JSON end point

https://rest.nexmo.com/call/json

XML end point

https://rest.nexmo.com/call/xml

All requests require your API credentials, which you can find under "API Settings" in Nexmo Dashboard.

Parameters

Parameter Description
api_key Required. Your API Key. Ex: api_key=n3xm0rocks
api_secret Required. Your API Secret. Ex: api_secret=12ab34cd
to Required. Phone number in international format and one recipient per request. Ex: to=447525856424 when sending to UK
from Optional. A voice enabled inbound number associated with your account.
answer_url Required. A URL to which Nexmo will send a request when the call is answered. Should contain a VoiceXML response.
answer_method Optional. The HTTP method for your answer_url. Must be GET (default) or POST.
error_url Optional. A URL to which Nexmo will send a request when an error occurs requesting or executing the VoiceXML returned by answer_url.
error_method Optional. The HTTP method for your error_url. Must be GET (default) or POST.
status_url Optional. A URL to which Nexmo will send a request when the call ends to notify your application.
status_method Optional. The HTTP method for your status_url. Must be GET (default) or POST.
machine_detection Optional. Expected values are true or hangup.
machine_timeout Optional. Time used to distinguish between human and machine events (default is 4000ms, maximum is 10000ms).

Response

After submitting a request to the Nexmo API, you will receive an HTTP response and a delivery receipt to the URL of your choosing (if you specified a callback URL in your request). The HTTP response will contain either a JSON object or XML string, depending on the base URL you chose to submit your request and indicates the success or failure for the Nexmo platform. The definitive final status of the call, however, would be confirmed by a callback request to your server.

JSON response

{
"call-id":"${callId}",
"to":"${to}",
"status":"${status}",
"error-text":"${error-text}"
}

XML response

<?xml version='1.0' encoding='UTF-8' ?>
<call-submission-response>
<call-id>${callId}</call-id>
<to>${to}</to>
<status>${status}</status>
<error-text>${error-text}</error-text>
</call-submission-response>

It will contain the following object/array keys and values:

Key Value
call-id Unique call identifier (alphanumeric up to 40 characters).
to Caller recipient number.
status The return code.
error-text If an error occurred, this will explain in readable terms the error encountered.

Response Codes

Code Error Text Meaning
0 Success The request was successfully accepted for delivery by Nexmo
1 Invalid credentials The api_key / api_secret you supplied is either invalid or disabled
2 Missing params Your request is incomplete and missing some mandatory parameters
4 Invalid destination address The recipient address has not a valid format.
5 Cannot route the call The Nexmo platform was unable to process this message, for example, an un-recognized number prefix
6 Number barred The number you are trying to reachis blacklisted and may not receive messages
7 Partner quota exceeded Your account does not have sufficient credit to process this request
99 Internal error An error has occurred in the Nexmo platform whilst processing this request

Call status

If the call request includes a callback parameter we will confirm whether your call has reached the recipient's phone. The request parameters sent sent via a GET (default) to your URL include the following parameters.

Parameter Value
call-id Call ID.
to Call destination.
status Status of message.
call-price Total price charged to your account in EUR.
call-rate Price per min in EUR.
call-duration Duration of the call in seconds
call-request Request time YYYY-MM-DD HH:MM:SS
call-start Start time YYYY-MM-DD HH:MM:SS
call-end End time YYYY-MM-DD HH:MM:SS
network-code Optional identifier of the recipient's telephone network.

Status parameters may have the following possible values:

Status Meaning
ok Call has terminated normally.
failed Failed call.
error An error occured during the call
blocked Call has been blocked.
machine Call has been stopped due to machine detection.

VoiceXML

VoiceXML has tags that can instruct the voice browser to provide speech synthesis, automatic speech recognition, dialog management, and audio playback.

Before starting, you would need to purchase a voice-enabled number from your Nexmo Dashboard. In order to forward incoming calls for your voice-enabled number to your VoiceXML script, you will need to set the voice callback accordingly using our Dev API Number Update

POST /number/update?api_key={api_key}&api_secret={api_secret}&country={country}&msisdn={msisdn}&moHttpUrl={url}&moSmppSysType={sysType}&voiceCallbackType={type}&voiceCallbackValue={value}

Where voiceCallbackType should be set to vxml and voiceCallbackValue to your callback URL, which will be generating the VoiceXML script.

Your VoiceXML callback URL will need to generate a VoiceXML document, Nexmo will send the caller id details (using nexmo_caller_id parameter) in the request sent to your callback URL.

Example: Play text-to-speech and audio

<?xml version="1.0" encoding="UTF-8"?>
<vxml version = "2.1" >
   <form>
      <block>
         <prompt>
            Hello.
         </prompt>
         <audio src="http://www.freesfx.co.uk/rx2/mp3s/9/10778_1380921485.mp3"/>
         <prompt xml:lang="es-mx-female">
            Hola.
         </prompt>
      </block>
   </form>
</vxml>

Supported languages can be found here.

Example: Voicemail

<?xml version="1.0" encoding="UTF-8"?>
<vxml version = "2.1" >
   <var name="callerid" expr="TO_BE_SET_BY_THE_SCRIPT" />
   <form>
   <record name="recording" beep="true" dtmfterm="true" maxtime="100s">
      <prompt>
      Please start your recording at the sound of the beep.
      </prompt>
      <prompt>
      After you are finished, you may press any DTMF key to indicate that you are done recording.
      </prompt>
   <filled>
      <prompt>
      Your recording was <value expr="recording" />
      </prompt>
      <submit next="http://myserver/record.php" method="post" namelist="recording callerid" enctype="multipart/form-data"/>
   </filled>
   </record>
   </form>
</vxml>

Below you will find a sample of PHP code demonstrating how to save the recording on your end. Please note the code should return a VoiceXML response.

<?php
// get our caller id to help identify the recording
$callerid = $_REQUEST['callerid'];
if ($_FILES["recording"]["error"] > 0) {
// oops, something went wrong. let's let our app know
header("HTTP/1.1 500 Internal Server Error");
echo "Return Code: " . $_FILES["recording"]["error"] . "
";
} else {
// copy our temp file to our real file name and save it on the server.
move_uploaded_file($_FILES["recording"]["tmp_name"],"./" . $callerid . "-" . date("His") . ".wav");
}
?>
<vxml version = "2.1" >
   <form>
      <block>
         <exit/>
      </block>
   </form>
</vxml>

Example: Transfer the call to a phone number

<?xml version="1.0" encoding="UTF-8"?>
<vxml version = "2.1" >
   <form id="CallTransfer">
      <block>
      <prompt>
      Please wait while we transfer the call
      </prompt>
      </block>
      <transfer name="MyCall" dest="tel:+4400000" bridge="true" connecttimeout="20s">
         <filled>
            <if cond="MyCall == 'busy'">
            <prompt>
         The recipient number is busy.
            </prompt>
            <exit/>
            <elseif cond="MyCall == 'noanswer'"/>
            <prompt>
         The recipient number is not answering.
            </prompt>
            </if>
      </filled>
      </transfer>
   </form>
</vxml>

Example: Menu with call transfer

<?xml version="1.0" encoding="UTF-8"?>
<vxml version = "2.1" >
   <menu dtmf="true">
      <property name="inputmodes" value="dtmf"/>
      <prompt>
         For sales press 1, For support press 2.
      </prompt>
      <choice dtmf="1" next="#sales"/>
      <choice dtmf="2" next="#support"/>
      </menu>
   <form id="sales">
      <block>
      <prompt>
         Please wait while we transfer the call
      </prompt>
      </block>
         <transfer name="MyCall" dest="tel:+4400000001" bridge="true" connecttimeout="20s"/>
      </form>
      <form id="support">
      <block>
      <prompt>
         Please wait while we transfer the call
      </prompt>
      </block>
         <transfer name="MyCall" dest="tel:+4400000002" bridge="true" connecttimeout="20s"/>
   </form>
</vxml>

USSD: Introduction

We are offering two types of interaction using USSD technology:

  • Push: Outbound notification
  • Prompt: Outbound notification with optional reply

Our USSD API is similar to our SMS API for request and response only the base URL is different:

Coverage & Pricing

Download Pricing

Push

JSON end point

https://rest.nexmo.com/ussd/json

XML end point

https://rest.nexmo.com/ussd/xml

Delivery Receipt are also supported.

Prompt

JSON end point

https://rest.nexmo.com/ussd-prompt/json

XML end point

https://rest.nexmo.com/ussd-prompt/xml

The response from the user will come back as an inbound message to your Nexmo's number used in the from parameter..

SMPP

For SMPP access you need to set the "service type" parameter to "ussd" or "ussd-prompt".


OAuth: Nexmo Authentication Flow

Introduction

When your application acts on behalf of our users, it's important that:

  • The application be able to identify the user
  • The user's privacy is protected
  • Nexmo can tell which application and user are making the request

To accomplish this, Nexmo uses the OAuth 1.0a protocol to give your application authorized access to the APIs. OAuth is a standard for negotiating developer authorization and granting access on behalf of Nexmo users to perform API requests. One of OAuth's benefits is the availability of many libraries, allowing developers to authenticate with Nexmo quickly and in a similar manner to how they authenticate with services such as Twitter and LinkedIn.

In summary, the OAuth flow can be described as:

  • An application requests a set of temporary credentials, also known as a request token. At this point this credentials isn't associated with a specific Nexmo user's account
  • The application redirects the user to a Nexmo login page where they authorize these temporary credentials (request token) to be associated with their Nexmo user's account
  • The application upgrades the temporary request token for permanent credentials, also known as an access token. These credentials are necessary to give the application access to the Nexmo APIs and make calls on behalf of the Nexmo user's account

We suggest that you use an existing OAuth Library for your programming language of choice.

Configuring Your Application

Feel free to contact us if you want to participate to the "Apps developer program".

Sign in to your Nexmo Dashboard and select the "Apps" section.




Click on the "Developer" link and register your application:




And receive your "consumer key" and "consumer secret" required for the OAuth interaction:




Nexmo OAuth end points:

  • Request Token: https://dashboard.nexmo.com/oauth/request_token
  • Authorize: https://dashboard.nexmo.com/oauth/authorize
  • Authenticate: https://dashboard.nexmo.com/oauth/authenticate
  • Access Token: https://dashboard.nexmo.com/oauth/access_token

Once the OAuth handshaking completed, you will be able to use Nexmo APIs on behalf of the Nexmo user's account, replace "api_key" and "api_secret" by OAuth parameters.

Checkout our code sample from Github.



Amazon SNS

Using Nexmo SDK you can easily subscribe your mobile users to a given topic and they will be automatically notified via SMS when you will be publishing messages.

Before you get started

  • Open a Nexmo account

Configure Amazon SNS

You will need to sign-up for an Amazon SNS account, you can do it here

From the Amazon web console select the SNS tab

Create a new topic: Choose a topic name

Give access to your new topic: From the "All Topic Actions" select "View/Edit Topic Policy"

Enter the Nexmo SNS Id 5646-2376-7830 in "Only these AWS users" for "Publishers" and "Subscribers" and click "Update Policy"

Download our Java SDK v1.4

Our Java SDK SNS enabled can be found here.

Quick Start

To compile the SDK and execute the Amazon SNS example, issue the following command:

ant clean sns-example

This will construct a message request and use the SDK to attempt to submit it.

The code can be seen in this class "src/com/nexmo/sns/sdk/examples/SubscribeAndPublishExample.java"

You can modify the constants at the top of the class to inject your own account credentials and message parameters.

public static final String API_KEY = "your API key";
public static final String API_SECRET = "your API secret";
public static final String SMS_FROM = "MyCompany20";
public static final String SMS_TO = "447525856424";
public static final String SMS_TEXT = "JavaSDK-Hello World!";
public static final String TOPIC_ARN = "arn:was:sns:us-east-1:10000000009:my_sms_channel";

Additionally you can browse SDK source and view Java Documentation.

Installation

You need to copy the nexmo-sdk.jar to your application and ensure that it is in your classpath. Additionally, there are some library dependencies under the /lib dir that must also be copied to your applications classpath if they are not already there.

The Nexmo Java SDK is then available for use. All configuration is passed as parameters on the constructors of the various objects.

Usage

To submit a message, first you should instantiate a NexmoSnsClient, the credentials for your Nexmo account on the constructor.

Then, you should instantiate a SubscribeRequest to subscribe a phone number to the SNS service.

Once you have a request object, you simply pass this to the submit() method in the NexmoSnsClient instance.

This method will return a SubscribeResult, including the service subscription status.

Create a request PublishRequest to publish a message t...one number and use the submit() method in the NexmoSnsClient instance.

This method will return a PublishResult , including the message submission status.

The list of possible return codes:

public static final int STATUS_OK = 0;
public static final int STATUS_BAD_COMMAND = 1;
public static final int STATUS_INTERNAL_ERROR = 2;
public static final int STATUS_INVALID_ACCOUNT = 3;
public static final int STATUS_MISSING_TOPIC = 4;
public static final int STATUS_INVALID_OR_MISSING_MSISDN = 5;
public static final int STATUS_INVALID_OR_MISSING_FROM = 6;
public static final int STATUS_INVALID_OR_MISSING_MSG = 7;
public static final int STATUS_TOPIC_NOT_FOUND = 8;
public static final int STATUS_TOPIC_PERMISSION_FAILURE = 9;
public static final int STATUS_COMMS_FAILURE = 13;

Nexmo Sandbox

Nexmo Sandbox provides an opportunity for developers to quickly test using the Nexmo REST or SMPP API without opening a production account. This can be very useful for load testing and/or regression testing. You can create a new test account simply by filling in the form below. With this account you will be sending message requests to our Sandbox environment. API responses will look just like those in production, but the messages won't be delivered to any real handset. Instead they will be logged in our shared Sandbox Inbox Folder.

From within the Sandbox Inbox Folder you will be able to test receiving Delivery Receipts (with a selection of statuses and error codes) to your DLR callback URL or SMPP client.

To start using our Sandbox, please create an account using the following form:

/ sec

If you disable quota, you can send unlimited messages - this might be helpful for load testing.

If quota is enabled then 0.05 cents will be subtracted from your test account balance upon each message sent.