Login Registration
8 (800) 333-21-60 [email protected]
Order the newsletter
DEVELOPMENT

Documentation

IM-messages WhatsApp, Viber, Telegram, iMessage

Developer Documentation

Welcome to the Nexmo Developer Documentation. Get familiar with concepts common to our APIs and products. Then start building connected applications with us.

Write the code

curl -X GET "https://api.nexmo.com/verify/json?&api_key=$NEXMO_API_KEY&api_secret=$NEXMO_API_SECRET&number=$RECIPIENT_NUMBER&brand=AcmeInc"

Write the code

nexmo.verify.request({ number: RECIPIENT_NUMBER,
brand: NEXMO_BRAND_NAME
}, (err, result) => {
if (err) {
console.error(err);
} else {
const verifyRequestId = result.request_id;
console.log('request_id', verifyRequestId);
}
});

Write the code

VerifyResponse response = client.getVerifyClient().verify(RECIPIENT_NUMBER, "NEXMO");
if (response.getStatus() == VerifyStatus.OK) {
System.out.printf("RequestID: %s", response.getRequestId());
} else {
System.out.printf("ERROR! %s: %s", response.getStatus(), response.getErrorText());
}

Write the code

var start = Client.NumberVerify.Verify(new NumberVerify.VerifyRequest
{
number = RECIPIENT_NUMBER,
brand = "AcmeInc"
});
Session["requestID"] = start.request_id;

Write the code

$verification = new \Nexmo\Verify\Verification(RECIPIENT_NUMBER, 'Acme Inc');
$client->verify()->start($verification);

Write the code

response = client.start_verification(number=RECIPIENT_NUMBER, brand="AcmeInc")
if response["status"] == "0":
print("Started verification request_id is %s" % (response["request_id"]))
else:
print("Error: %s" % response["error_text"])

Write the code

response = client.verify.request(
number: RECIPIENT_NUMBER,
brand: 'AcmeInc'
)
if response.status == '0'
# display the Verify `request_id`
puts response.request_id
else
puts response.error_text
end

Concepts

There are a number of shared concepts between the various Nexmo APIs:

  • Applications - Security and configuration information you need to connect to Nexmo endpoints
  • Authentication – API keys, OAuth, and JSON Web Tokens (JWTs)
  • OAuth – How to use OAuth 1.0a with Nexmo's API
  • Signing messages – How to cryptographically sign messages and verify signatures
  • Webhooks – Nexmo's API can send data back to your web server via a webhook

You can also find definitions of commonly used terms in the Glossary.

Products

Documentation within Nexmo Developer is organised by product. Within each product section you'll find the following types of documentation:

  • Guides - Key concepts highlighting core functionality and features
  • Building Blocks - Quick access code samples to help you construct your programmable communications apps
  • Tutorials - Step-by-step tutorials to help you build solutions to common communications use cases
  • API Reference - The resources, parameters and payload examples

Messages and Dispatch Beta

Integrate with various communication channels including Facebook Messenger, WhatsApp and Viber with failover

  • Send and receive

    SMS

    • Overview
    • Building Blocks
    • Guides
    • Tutorials
    API Reference
  • Send and receive

    Voice

    • Overview
    • Building Blocks
    • Guides
    • Tutorials
    API Reference

Link your Facebook Page to your Nexmo account

Next you'll need to link your Facebook Page to your Nexmo account. This will allow Nexmo to handle the inbound messages and allow you to send messages from the Nexmo Messages API.

Important: This process needs to be authenticated by JWT. The JWT generated in this case can be based on any Application ID in your account, as this JWT is only used to authenticate the linking process, and it not used to authenticate application-specific API calls.

You will need to paste in a valid JWT. If you don't have one you can create one as follows:

  1. Work with existing customers
  2. With site visitors who have not yet made a purchase
  3. With an external audience.

SMS API

For sending and receiving SMS

Alerts API - Subscription

For subscribing users to event-based alerts with US Short Codes

Alerts API - Sending

For sending event-based alerts to users with US Short Codes

2FA

For verifying users with US Short Codes

Overview

There are a number of shared concepts between the Nexmo APIs: the use of JSON Web Tokens (JWTs), signed requests, OAuth tokens, and webhooks. The guides below explain in detail how to use these elements.

Guides

  • Applications - Security and configuration information you need to connect to Nexmo endpoints.
  • Authentication - API keys, OAuth, and JSON Web Tokens (JWTs).
  • OAuth - how to use OAuth 1.0a with Nexmo's API.
  • Signing messages - how to cryptographically sign messages and verify message signatures.
  • Webhooks - Nexmo's API can send data back to your web server via a webhook.
  • Glossary - A glossary of common terms used throughout the Nexmo platform.

Number format

Within the Nexmo APIs, all phone numbers are in E.164. This means that numbers:

  • Omit both a leading + and the international access code such as 00 or 001.
  • Contain no special characters, such as space, () or -

For example, a US number would have the format 14155550101. A UK number would have the format 447700900123.

If you are unsure how to format the number, the API Number Insight can be used to find correct information about a number.

See also Number format in the Voice API documentation.

GUIDES

  • Applications - Security and configuration information you need to connect to Nexmo endpoints.
  • Authentication – API keys, OAuth, and JSON Web Tokens (JWTs).
  • OAuth – how to use OAuth 1.0a with Nexmo's API.
  • Signing messages – how to cryptographically sign messages and verify message signatures.
  • Webhooks – Nexmo's API can send data back to your web server via a webhook.
  • Glossary – A glossary of common terms used throughout the Nexmo platform.

Application

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.

Authentication

Nexmo API provides various means of Authentication depending on what product you are using.

OAuth

You can use the OAuth 1.0a protocol to give your App authorized access to the Nexmo APIs.

OAuth is an open standard that provides client apps with secure delegated access to HTTP resources on behalf of that resource's owner. It does this by providing access tokens to third-party clients with the approval of the resource owner. The client then uses the access token to access protected resources.

When you use OAuth for authentication:

  • Nexmo can tell which App and user are calling Nexmo APIs
  • Your app identifies the user
  • The user's privacy is protected
  • Note: We strongly recommend you use an existing OAuth Library for your App.

This section contains:

  • Setting up OAuth access
  • Using OAuth in your App
  • Running the sample App

Signing messages

You can use signatures with Nexmo when both sending and receiving SMS messages. When sending, you generate a signature to send with your message. When receiving, the incoming webhook will include the signature and all the fields you need to generate the signature in your application to verify that the two signatures match.

You use a signature to:

  • Verify that a request originates from a trusted source
  • Ensure that the message has not been tampered with en-route
  • Defend against interception and later replay

Webhooks

Webhooks are an extension of an API, but instead of your code requesting data from Nexmo, Nexmo sends data to you. The data arrives in a web request to your application. A webhook may be the result of an earlier API call (this type of webhook is also called a "callback"), such as an asynchronous request to the Number Insight API. Webhooks are also used to notify your application of events such as an incoming call or message.

Since the Nexmo servers need to be able to send data to your application via webhooks, you need to set up a webserver to receive the incoming HTTP requests. You also need to specify the URL of each webhook on your webserver so that data can be sent to each one.

Glossary

Two-factor authentication: unambiguous identification of users by means of the combination of two different components. For example, to withdraw cash from an ATM, you need both a card and a PIN code. These components may be something that the user knows, something that the user possesses or something that is inseparable from the user.

Many Nexmo customers authenticate their users by sending them a PIN code in an SMS. The user authenticates by entering the PIN into the customer's UI. An example of usage is where the customer requires a password reset. In this case, the two components are the account details and possession of the phone number registered to that account.

See the Wikipedia article.

See also the Verify API documentation.

Overview

There are a number of shared concepts between the Nexmo APIs: the use of JSON Web Tokens (JWTs), signed requests, OAuth tokens, and webhooks. The guides below explain in detail how to use these elements.

Guides

  • Applications - Security and configuration information you need to connect to Nexmo endpoints.
  • Authentication - API keys, OAuth, and JSON Web Tokens (JWTs).
  • OAuth - how to use OAuth 1.0a with Nexmo's API.
  • Signing messages - how to cryptographically sign messages and verify message signatures.
  • Webhooks - Nexmo's API can send data back to your web server via a webhook.
  • Glossary - A glossary of common terms used throughout the Nexmo platform.

Number format

Within the Nexmo APIs, all phone numbers are in E.164. This means that numbers:

  • Omit both a leading + and the international access code such as 00 or 001.
  • Contain no special characters, such as space, () or -

For example, a US number would have the format 14155550101. A UK number would have the format 447700900123.

If you are unsure how to format the number, the API Number Insight can be used to find correct information about a number.

See also Number format in the Voice API documentation.

GUIDES

  • Applications - Security and configuration information you need to connect to Nexmo endpoints.
  • Authentication – API keys, OAuth, and JSON Web Tokens (JWTs).
  • OAuth – how to use OAuth 1.0a with Nexmo's API.
  • Signing messages – how to cryptographically sign messages and verify message signatures.
  • Webhooks – Nexmo's API can send data back to your web server via a webhook.
  • Glossary – A glossary of common terms used throughout the Nexmo platform.

Messages API

For messaging through SMS/MMS, Facebook Messenger, WhatsApp and Viber Service Messages.

Dispatch API

For orchestrating messaging workflows with failover.

External Accounts API

For managing your Facebook Messenger, WhatsApp and Viber Service Messages accounts for use with Messages and Dispatch APIs.

Overview

There are a number of shared concepts between the Nexmo APIs: the use of JSON Web Tokens (JWTs), signed requests, OAuth tokens, and webhooks. The guides below explain in detail how to use these elements.

Guides

  • Applications - Security and configuration information you need to connect to Nexmo endpoints.
  • Authentication - API keys, OAuth, and JSON Web Tokens (JWTs).
  • OAuth - how to use OAuth 1.0a with Nexmo's API.
  • Signing messages - how to cryptographically sign messages and verify message signatures.
  • Webhooks - Nexmo's API can send data back to your web server via a webhook.
  • Glossary - A glossary of common terms used throughout the Nexmo platform.

Number format

Within the Nexmo APIs, all phone numbers are in E.164. This means that numbers:

  • Omit both a leading + and the international access code such as 00 or 001.
  • Contain no special characters, such as space, () or -

For example, a US number would have the format 14155550101. A UK number would have the format 447700900123.

If you are unsure how to format the number, the API Number Insight can be used to find correct information about a number.

See also Number format in the Voice API documentation.

Application API

Create and manage Nexmo applications used to configure & authenticate with Voice API

Conversion API

Improve your deliverability

Media API

Manage media items such as audio files for use with other Nexmo APIs.

Redact API

Redact your personal data in the Nexmo platform

Account

Get pricing, balance and account information

Messages

Retrieve inbound and outbound messages

Numbers

Buy, list and update your account numbers

Pricing

Retrieve details of service pricing

Verify API

Check to see if a user owns a number via both SMS and voice.

Verify API - Custom templates

You use custom templates to modify the default messages sent by the Verify API.

Voice API

For making and receiving calls.

Nexmo Call Control Objects (NCCO)

The JSON format for the Nexmo Voice API.

Number Insight API

The smart way to get real-time intelligence on numbers anywhere in the world and protect yourself from fraud and spam.

Conversation API

Create real-time communications channels for text, voice and video.

Application submitted
Your message has been sent successfully. In the near future our manager will contact you

Application submitted
Your message has been sent successfully. In the near future our manager will contact you

API Reference

Application submitted
Your message has been sent successfully. In the near future our manager will contact you

Application submitted
Your message has been sent successfully. In the near future our manager will contact you

Application submitted
Your message has been sent successfully. In the near future our manager will contact you

Contact us

Order a callback and we will call you back and answer all your questions or call us

By clicking the "Send" button, I give my consent to processing of personal data
Application submitted
Your message has been sent successfully. In the near future our manager will contact you