SMS API

With the Nexmo SMS API you can send SMS from your account and lookup messages both messages that you've sent as well as messages sent to your virtual numbers. Numbers are specified in E.164 format.

Download OpenAPI 3 Definition

Install the Nexmo library

$ npm install --save nexmo

Install the Nexmo library

Add the following to build.gradle:

repositories {
    mavenCentral()
}

dependencies {
    compile 'com.nexmo:client:2.0.2'
}

Install the Nexmo library

$ composer require nexmo/client:@beta

Install the Nexmo library

$ pip install nexmo

Install the Nexmo library

$ gem install nexmo

Initialize the library

const Nexmo = require('nexmo')

const nexmo = new Nexmo({
  apiKey: NEXMO_API_KEY,
  apiSecret: NEXMO_API_SECRET
})

Initialize the library

AuthMethod auth = new TokenAuthMethod(NEXMO_API_KEY, NEXMO_API_SECRET);
NexmoClient client = new NexmoClient(auth);

Initialize the library

$basic  = new \Nexmo\Client\Credentials\Basic(NEXMO_API_KEY, NEXMO_API_SECRET);
$client = new \Nexmo\Client($basic);

Initialize the library

import nexmo

client = nexmo.Client(key=NEXMO_API_KEY, secret=NEXMO_API_SECRET)

Initialize the library

require 'nexmo'

client = Nexmo::Client.new(
  api_key: NEXMO_API_KEY,
  api_secret: NEXMO_API_SECRET
)

SMS

The SMS object contains information about the request and details of the message information.

  • Key
    Description
  • message-count
    integer

    The amount of messages in the request

  • messages
    array
    of object's
  • Key
    Description
  • messages
    array
    of object's

Example Model

{
  "message-count": 1,
  "messages": [
    {
      "to": "447700900000",
      "message-id": "0A0000000123ABCD1",
      "status": "0",
      "remaining-balance": "3.14159265",
      "message-price": "0.03330000",
      "network": "12345"
    }
  ]
}

Example Model

<?xml version="1.0" encoding="UTF-8"?>
<mt-submission-response>
  <messages count="1">
    <message>
      <to>447700900000</to>
      <messageId>0A0000000123ABCD1</messageId>
      <status>0</status>
      <remainingBalance>3.14159265</remainingBalance>
      <messagePrice>0.03330000</messagePrice>
      <network>12345</network>
    </message>
  </messages>
</mt-submission-response>

Send an SMS

Send an outbound SMS from your Nexmo account

POST https://rest.nexmo.com /sms/:format

Path Parameters

  • Key
    Description
    Example
    Default
  • format
    Required | string

    The format of the response


    Must be one of: jsonorxml
    json
    None

Query Parameter

  • Key
    Description
    Example
    Default
  • api_key
    Required | string

    Your API key

    abcd1234
    None
  • api_secret
    string

    Your API secret. Required unless sig is provided

    abcdef0123456789
    None
  • sig
    string

    The hash of the request parameters in alphabetical order, a timestamp and the signature secret. See Signing Requests for more details.

    None
    None

Request body application/x-www-form-urlencoded

  • Key
    Description
    Example
    Default
  • from
    Required | string

    The name or number the message should be sent from. Alphanumeric senderID's are not supported in all countries, see Global Messaging for more details. If alphanumeric, spaces will be ignored. Numbers are specified in E.164 format.

    AcmeInc
    None
  • to
    Required | string

    The number that the message should be sent to. Numbers are specified in E.164 format.

    447700900000
    None
  • text
    string

    The body of the message being sent. If your message contains characters that can be encoded according to the GSM Standard and Extended tables then you can set the type to text. If your message contains characters outside this range, then you will need to set the type to unicode.

    Hello World!
    None
  • ttl
    integer

    Advanced: The duration in milliseconds the delivery of an SMS will be attempted.

    By default Nexmo attempt delivery for 72 hours, however the maximum effective value depends on the operator and is typically 24 - 48 hours. We recommend this value should be kept at its default or at least 30 minutes.


    Must be between 20000 and 604800000
    900000
    259200000
  • status-report-req
    boolean

    Advanced: Boolean indicating if you like to receive a Delivery Receipt.

    None
    true
  • callback
    string

    Advanced: The webhook endpoint the delivery receipt for this sms is sent to. This parameter overrides the webhook endpoint you set in Dashboard.

    https://example.com/sms-dlr
    None
  • message-class
    integer

    Advanced: The Data Coding Scheme value of the message


    Must be one of: 0, 1, 2or3
    None
    None
  • type
    string

    Advanced: The format of the message body


    Must be one of: text, binary, wappush, unicode, vcalorvcard
    text
    text
  • vcard
    string (vcard)

    Advanced: A business card in vCard format  . Depends on type parameter having the value vcard.

    None
    None
  • vcal
    string (vcal)

    Advanced: A calendar event in vCal format  . Depends on type parameter having the value vcal.

    None
    None
  • body
    string

    Advanced: Hex encoded binary data. Depends on type parameter having the value binary.

    638265253311
    None
  • udh
    string

    Advanced: Your custom Hex encoded User Data Header  . Depends on type parameter having the value binary.

    06050415811581
    None
  • protocol-id
    integer

    Advanced: The value of the protocol identifier  to use. Ensure that the value is aligned with udh.

    127
    None
  • title
    string

    Advanced: The title for a wappush SMS. Depends on type parameter having the value wappush.

    Welcome
    None
  • url
    string

    Advanced: The URL of your website. Depends on type parameter having the value wappush.

    https://example.com
    None
  • validity
    string

    Advanced: The availability for an SMS in milliseconds. Depends on type parameter having the value wappush.

    300000
    None
  • client-ref
    string

    Advanced: You can optionally include your own reference of up to 40 characters.

    my-personal-reference
    None

View response field descriptions


Example request

curl -X "POST" "https://rest.nexmo.com/sms/json" \
  -d "from=Acme Inc" \
  -d "text=A text message sent using the Nexmo SMS API" \
  -d "to=TO_NUMBER" \
  -d "api_key=NEXMO_API_KEY" \
  -d "api_secret=NEXMO_API_SECRET"

const from = 'Acme Inc'
const to = TO_NUMBER
const text = 'A text message sent using the Nexmo SMS API'

nexmo.message.sendSms(from, to, text)

SmsClient client = new NexmoClient(auth).getSmsClient();

TextMessage exampleMessage = new TextMessage(
    "Acme Inc",
    TO_NUMBER,
    "A text message sent using the Nexmo SMS API"
);

});

var results = client.SMS.Send(request: new SMS.SMSRequest
{
    from = "Acme Inc",
    to = TO_NUMBER,
    text = "A test SMS sent using the Nexmo SMS API"
});

var results = client.SMS.Send(request: new SMS.SMSRequest
{
    from = "Acme Inc",
    to = TO_NUMBER,
    text = "A test SMS sent using the Nexmo SMS API"
});

$message = $client->message()->send([
    'to' => TO_NUMBER,
    'from' => 'Acme Inc',
    'text' => 'A text message sent using the Nexmo SMS API'
]);

client.send_message({
    'from': 'Acme Inc',
    'to': TO_NUMBER,
    'text': 'A text message sent using the Nexmo SMS API',
})

client.sms.send(
  from: 'Acme Inc',
  to: RECIPIENT_NUMBER,
  text: 'A text message sent using the Nexmo SMS API'
)

200 HTTP response 

{
  "to": "447700900000",
  "message-id": "0A0000000123ABCD1",
  "status": "0",
  "remaining-balance": "3.14159265",
  "message-price": "0.03330000",
  "network": "12345"
}
<?xml version="1.0" encoding="UTF-8"?>
<mt-submission-response>
  <messages count="1">
    <message>
      <to>447700900000</to>
      <messageId>0A0000000123ABCD1</messageId>
      <status>0</status>
      <remainingBalance>3.14159265</remainingBalance>
      <messagePrice>0.03330000</messagePrice>
      <network>12345</network>
    </message>
  </messages>
</mt-submission-response>

Callback  Delivery Receipt

The following are parameters sent in as a delivery receipt callback. You can subscribe to webhooks to receive notification when the delivery status of an SMS that you have sent with Nexmo changes.

POST https://example.com /webhooks/delivery-receipt

Request body application/json

  • Key
    Description
    Example
  • msisdn
    string

    The number the message was sent to. Numbers are specified in E.164 format.

    447700900000
  • to
    string

    The SenderID you set in from in your request.

    AcmeInc
  • network-code
    string

    The Mobile Country Code Mobile Network Code (MCCMNC) of the carrier this phone number is registered with.

    12345
  • messageId
    string

    The Nexmo ID for this message.

    0A0000001234567B
  • price
    string

    The cost of the message

    0.03330000
  • status
    string

    A code that explains where the message is in the delivery process.


    Will be one of: delivered, expired, failed, rejected, accepted, bufferedorunknown
    delivered
  • scts
    string

    When the DLR was recieved from the carrier in the following format YYMMDDHHMM. For example, 2001011400 is at 2020-01-01 14:00

    2001011400
  • err-code
    string

    The status of the request. Will be a non 0 value if there has been an error. See the SMS error reference for more details

    0
  • message-timestamp
    string

    The time when Nexmo started to push this Delivery Receipt to your webhook endpoint.

    2020-01-01 12:00:00 +0000

Request model

{
  "msisdn": "447700900000",
  "to": "AcmeInc",
  "network-code": "12345",
  "messageId": "0A0000001234567B",
  "price": "0.03330000",
  "status": "delivered",
  "scts": "2001011400",
  "err-code": "0",
  "message-timestamp": "2020-01-01T12:00:00.000+00:00"
}

Webhook  Inbound SMS

If you rent one or more virtual numbers from Nexmo, inbound messages to that number are sent to your webhook endpoint.

When you receive an inbound message, you must send a 2xx response. If you do not send a 2xx response Nexmo will resend the inbound message for the next 24 hours.

POST https://example.com /webhooks/inbound-sms

Request body application/json

  • Key
    Description
    Example
  • msisdn
    Required | string

    The phone number that this inbound message was sent from. Numbers are specified in E.164 format.

    447700900001
  • to
    Required | string

    The phone number the message was sent to. This is your virtual number. Numbers are specified in E.164 format.

    447700900000
  • messageId
    Required | string

    The ID of the message

    0A0000000123ABCD1
  • text
    Required | string

    The message body for this inbound message.

    Hello world
  • type
    Required | string

    Possible values are:

    • text - standard text.
    • unicode - URLencoded unicode . This is valid for standard GSM, Arabic, Chinese, double-encoded characters and so on.
    • binary - a binary message.
    text
  • keyword
    Required | string

    The first word in the message body. This is typically used with short codes.

    Hello
  • message-timestamp
    Required | string

    The time when Nexmo started to push this Delivery Receipt to your webhook endpoint.

    2020-01-01 12:00:00 +0000
  • timestamp
    string

    A unix timestamp representation of message-timestamp.

    1578787200
  • nonce
    string

    A random string that forms part of the signed set of parameters, it adds an extra element of unpredictability into the signature for the request. You use the nonce and timestamp parameters with your shared secret to calculate and validate the signature for inbound messages.

    aaaaaaaa-bbbb-cccc-dddd-0123456789ab
  • concat
    string

    True - if this is a concatenated message.

    true
  • concat-ref
    string

    The transaction reference. All parts of this message share this value.

    1
  • concat-total
    string

    The number of parts in this concatenated message.

    3
  • concat-part
    string

    The number of this part in the message. Counting starts at 1.

    2
  • data
    string (binary)

    The content of this message, if type is binary.

    None
  • udh
    string

    The hex encoded User Data Header, if type is binary

    None

Request model

{
  "msisdn": "447700900001",
  "to": "447700900000",
  "messageId": "0A0000000123ABCD1",
  "text": "Hello world",
  "type": "text",
  "keyword": "Hello",
  "message-timestamp": "2020-01-01T12:00:00.000+00:00",
  "timestamp": "1578787200",
  "nonce": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "concat": "true",
  "concat-ref": "1",
  "concat-total": "3",
  "concat-part": "2",
  "data": "abc123",
  "udh": "abc123"
}

Errors

Nexmo uses error codes to report back when an issue was encountered. Below you can find a full table to error codes:

Code Text Meaning
1 Throttled You have exceeded the submission capacity allowed on this account. Please wait and retry.
2 Missing params Your request is incomplete and missing some mandatory parameters.
3 Invalid params The value of one or more parameters is invalid.
4 Invalid credentials The api_key / api_secret you supplied is either invalid or disabled.
5 Internal error There was an error processing your request in the Platform.
6 Invalid message The Platform was unable to process your request. For example, due to an unrecognised prefix for the phone number.
7 Number barred The number you are trying to submit to is blacklisted and may not receive messages.
8 Partner account barred The api_key you supplied is for an account that has been barred from submitting messages.
9 Partner quota exceeded Your pre-paid account does not have sufficient credit to process this message.
11 Account not enabled for REST This account is not provisioned for REST submission, you should use SMPP instead.
12 Message too long The length of udh and body was greater than 140 octets for a binary type SMS request.
13 Communication Failed Message was not submitted because there was a communication failure.
14 Invalid Signature Message was not submitted due to a verification failure in the submitted signature.
15 Illegal Sender Address - rejected Due to local regulations, the SenderID you set in from in the request was not accepted. Please check the Global messaging section.
16 Invalid TTL The value of ttl in your request was invalid.
19 Facility not allowed Your request makes use of a facility that is not enabled on your account.
20 Invalid Message class The value of message-class in your request was out of range. See https://en.wikipedia.org/wiki/Data_Coding_Scheme.
23 Bad callback :: Missing Protocol You did not include https in the URL you set in callback.
29 Non White-listed Destination The phone number you set in to is not in your pre-approved destination list. To send messages to this phone number, add it using Dashboard.
34 Invalid or Missing Msisdn Param The phone number you supplied in the to parameter of your request was either missing or invalid.

The following response codes are for 2FA and Campaign Subscription Management only.

Code Text
101 RESPONSE_INVALID_ACCOUNT_CAMPAIGN

The following response codes are for 2FA only.

Code Text Meaning
102 RESPONSE_MSISDN_OPTED_OUT_FOR_CAMPAIGN You tried to send a message to a destination number that has opted out of your program.

The following response codes are for Campaign Subscription Management only.

Code Text
102 RESPONSE_INVALID_CAMPAIGN_SHORTCODE
103 RESPONSE_INVALID_MSISDN

Example response

{
  "message-count": 1,
  "messages": [
    {
      "status": "2",
      "error-text": "Missing to param"
    }
  ]
}