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. More SMS API documentation is at https://developer.nexmo.com/messaging/sms/overview
Send an outbound SMS from your Nexmo account
POST
https://rest.nexmo.com/sms/:format
Key | Description | Example | Default |
---|---|---|---|
format Required | string |
The format of the response Must be one of: json or xml
|
json
|
json
|
Key | Description | Example | Default |
---|---|---|---|
api_key Required | string |
Your API key |
abcd1234
|
None |
api_secret string |
Your API secret. Required unless |
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 |
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 |
Hello World!
|
None |
ttl integer |
Advanced: The duration in milliseconds the delivery of an SMS will be attempted. 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 , 2 or 3
|
None | None |
type string |
Advanced: The format of the message body Must be one of: text , binary , wappush , unicode , vcal or vcard
|
text
|
text
|
vcard string | (vcard) |
Advanced: A business card in vCard format. Depends on |
None | None |
vcal string | (vcal) |
Advanced: A calendar event in vCal format. Depends on |
None | None |
body string |
Advanced: Hex encoded binary data. Depends on |
638265253311
|
None |
udh string |
Advanced: Your custom Hex encoded User Data Header. Depends on |
06050415811581
|
None |
protocol-id integer |
Advanced: The value of the protocol identifier to use. Ensure that the value is aligned with |
127
|
None |
title string |
Advanced: The title for a wappush SMS. Depends on |
Welcome
|
None |
url string |
Advanced: The URL of your website. Depends on |
https://example.com
|
None |
validity string |
Advanced: The availability for an SMS in milliseconds. Depends on |
300000
|
None |
client-ref string |
Advanced: You can optionally include your own reference of up to 40 characters. |
my-personal-reference
|
None |
account-ref string |
Advanced: An optional string used to identify separate accounts using the SMS endpoint for billing purposes. To use this feature, please email support@nexmo.com |
customer1234
|
None |
View response field descriptions
Field | Description | ||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
message-count
string |
The amount of messages in the request |
||||||||||||||||
messages
array of objects |
|||||||||||||||||
|
Field | Description |
---|
{
"message-count": 1,
"messages": [
{
"to": "447700900000",
"message-id": "0A0000000123ABCD1",
"status": "0",
"remaining-balance": "3.14159265",
"message-price": "0.03330000",
"network": "12345",
"account-ref": "customer1234"
}
]
}
<?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>
<account-ref>customer1234</account-ref>
</message>
</messages>
</mt-submission-response>
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
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 |
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 , buffered or unknown
|
delivered
|
scts string |
When the DLR was recieved from the carrier in the following format |
2001011400
|
err-code string |
The status of the request. Will be a non |
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
|
{
"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"
}
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
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
|
keyword Required | string |
The first word in the message body. Converted to upper case. |
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. This field does not exist if it is a single 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 |
{
"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"
}
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 |
{
"message-count": 1,
"messages": [
{
"status": "2",
"error-text": "Missing to param"
}
]
}