Getting Started with the Vonage SMS API
Short Message Service (SMS) is a text messaging service that uses standardized communication protocols to send short text messages to or between devices. These messages are transmitted via cellular networks.
Communications APIs, like Vonage’s Messages API, let you programmatically send SMS messages by making an HTTP request to an API endpoint. The message is then passed downstream to the cellular network for delivery to the recipient’s device.
The Messages API and the SMS API
There are currently two Vonage APIs with which you can send SMS Messages:
- The Messages API
- The SMS API
There are some differences between the two APIs which you may want to consider when deciding which one to use.
Messages API
- The Messages API is a multi-channel messaging API which supports other messaging channels as well as SMS
- This includes other network-based channels such as MMS and RCS, as well as OTT channels such as WhatsApp and Facebook Messenger
- All the channels use the same endpoint and the same basic structure for request payloads, so multiple channels can be used via a single integration
- The Messages API will continue to be enhanced with new features and support for network-based and OTT channels
- The Messages API provides a Messages Status webhook which supports the following statuses:
submitteddeliveredrejectedundeliverable
SMS API
- The SMS API is suitable for high throughput (e.g. > 500 messages/second) use cases (increased throughput levels are only available on request)
- The SMS API provides HIPAA compliance
- The SMS API provides Delivery Receipts for individual messages segments (where a lengthy message has been split into multiple parts for delivery).
- The SMS API Delivery Receipts support the following statuses:
accepteddeliveredbufferedexpiredfailedrejectedunknown
Customers sending SMS in the USA using 10 digit geographic phone numbers will need to follow the 10 DLC regulatory guidelines. See our 10 DLC documentation for further information.
Send an SMS
This example shows you how to send an SMS to your chosen number.
This example is specifically for use with the SMS API
First, sign up for a Vonage account if you don't already have one, and make a note of your API key and secret on the dashboard getting started page.
Replace the following placeholder values in the sample code:
| Key | Description |
|---|---|
VONAGE_API_KEY | Your Vonage API key. |
VONAGE_API_SECRET | Your Vonage API secret. |
Write the code
Add the following to send-sms.sh:
curl -X POST https://rest.nexmo.com/sms/json \
-d "from=${SMS_SENDER_ID}" \
-d "to=${SMS_TO_NUMBER}" \
-d 'text=A text message sent using the Vonage SMS API' \
-d "api_key=${VONAGE_API_KEY}" \
-d "api_secret=${VONAGE_API_SECRET}"Run your code
Save this file to your machine and run it:
Prerequisites
npm install @vonage/server-sdkCreate a file named send.js and add the following code:
const { Vonage } = require('@vonage/server-sdk');
const vonage = new Vonage({
apiKey: VONAGE_API_KEY,
apiSecret: VONAGE_API_SECRET,
});Write the code
Add the following to send.js:
vonage.sms.send({
to: SMS_TO_NUMBER,
from: SMS_SENDER_ID,
text: 'A text message sent using the Vonage SMS API',
})
.then((resp) => {
console.log('Message sent successfully');
console.log(resp);
})
.catch((err) => {
console.log('There was an error sending the messages.');
console.error(err);
});Run your code
Save this file to your machine and run it:
Prerequisites
Add the following to build.gradle:
implementation 'com.vonage:server-sdk-kotlin:2.1.1'Create a file named SendMessage and add the following code to the main method:
val client = Vonage {
apiKey(VONAGE_API_KEY)
apiSecret(VONAGE_API_SECRET)
}Write the code
Add the following to the main method of the SendMessage file:
val response = client.sms.sendText(
from = SMS_SENDER_ID,
to = SMS_TO_NUMBER,
message = "Hello from Vonage SMS API"
)
println(
if (response.wasSuccessfullySent())
"Message sent successfully."
else
"Message failed with error: ${response[0].errorText}"
)Run your code
We can use the application plugin for Gradle to simplify the running of our application. Update your build.gradle with the following:
apply plugin: 'application'
mainClassName = project.hasProperty('main') ? project.getProperty('main') : ''Run the following gradle command to execute your application, replacing com.vonage.quickstart.kt.sms with the package containing SendMessage:
Prerequisites
Add the following to build.gradle:
implementation 'com.vonage:server-sdk:9.3.1'Create a file named SendMessage and add the following code to the main method:
VonageClient client = VonageClient.builder().apiKey(VONAGE_API_KEY).apiSecret(VONAGE_API_SECRET).build();Write the code
Add the following to the main method of the SendMessage file:
TextMessage message = new TextMessage(
SMS_SENDER_ID, SMS_TO_NUMBER,
"A text message sent using the Vonage SMS API"
);
SmsSubmissionResponse response = client.getSmsClient().submitMessage(message);
if (response.getMessages().get(0).getStatus() == MessageStatus.OK) {
System.out.println("Message sent successfully.");
} else {
System.out.println("Message failed with error: " + response.getMessages().get(0).getErrorText());
}Run your code
We can use the application plugin for Gradle to simplify the running of our application. Update your build.gradle with the following:
apply plugin: 'application'
mainClassName = project.hasProperty('main') ? project.getProperty('main') : ''Run the following gradle command to execute your application, replacing com.vonage.quickstart.sms with the package containing SendMessage:
Prerequisites
Install-Package VonageCreate a file named SendSms.cs and add the following code:
using Vonage;
using Vonage.Request;Add the following to SendSms.cs:
var credentials = Credentials.FromApiKeyAndSecret(
vonageApiKey,
vonageApiSecret
);
var vonageClient = new VonageClient(credentials);Write the code
Add the following to SendSms.cs:
var response = await vonageClient.SmsClient.SendAnSmsAsync(new Vonage.Messaging.SendSmsRequest()
{
To = SMS_TO_NUMBER,
From = SMS_SENDER_ID,
Text = "A text message sent using the Vonage SMS API"
});
Console.WriteLine(response.Messages[0].To);Prerequisites
composer require vonage/clientCreate a file named send-sms.php and add the following code:
$keypair = new \Vonage\Client\Credentials\Keypair(VONAGE_PRIVATE_KEY, VONAGE_APPLICATION_ID);
$client = new \Vonage\Client($keypair);Write the code
Add the following to send-sms.php:
$response = $client->sms()->send(
new \Vonage\SMS\Message\SMS(TO_NUMBER, BRAND_NAME, 'A text message sent using the Vonage SMS API')
);
$message = $response->current();
if ($message->getStatus() == 0) {
echo "The message was sent successfully\n";
} else {
echo "The message failed with status: " . $message->getStatus() . "\n";
}Run your code
Save this file to your machine and run it:
Prerequisites
pip install vonage python-dotenvWrite the code
Add the following to send-an-sms.py:
from vonage import Auth, Vonage
from vonage_sms import SmsMessage, SmsResponse
client = Vonage(Auth(api_key=VONAGE_API_KEY, api_secret=VONAGE_API_SECRET))
message = SmsMessage(
to=SMS_TO_NUMBER,
from_=SMS_SENDER_ID,
text="A text message sent using the Vonage SMS API.",
)
response: SmsResponse = client.sms.send(message)
print(response)Run your code
Save this file to your machine and run it:
Prerequisites
gem install vonageCreate a file named send.rb and add the following code:
client = Vonage::Client.new(
api_key: VONAGE_API_KEY,
api_secret: VONAGE_API_SECRET
)Write the code
Add the following to send.rb:
client.sms.send(
from: SMS_SENDER_ID,
to: SMS_TO_NUMBER,
text: 'A text message sent using the Vonage SMS API'
)Run your code
Save this file to your machine and run it:
Troubleshooting
If you have problems when making API calls be sure to check the returned status field for specific error codes.
Important: If you are a U.S. customer using the SMS API to send traffic from a +1 Country Code 10 Digit Long Code (10 DLC) into US networks, you must register a brand and campaign in order to get approval for sending. Once approved, you must link a number to the campaign. See the 10 DLC Support section.
Vonage SMS API Concepts
Before using the Vonage SMS API, familiarize yourself with the following:
Number format - The SMS API requires phone numbers in E.164 format.
Authentication - The SMS API authenticates using your account API key and secret.
Webhooks - The SMS API makes HTTP requests to your application web server so that you can act upon them. For example: inbound SMS and delivery receipts.