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. |
Run your code
Save this file to your machine and run it:
Prerequisites
Create a file named send.js and add the following code:
Run your code
Save this file to your machine and run it:
Prerequisites
Add the following to build.gradle:
Create a file named SendMessage and add the following code to the main method:
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:
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:
Create a file named SendMessage and add the following code to the main method:
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:
Run the following gradle command to execute your application, replacing com.vonage.quickstart.sms with the package containing SendMessage:
Prerequisites
Create a file named SendSms.cs and add the following code:
Add the following to SendSms.cs:
Prerequisites
Create a file named send-sms.php and add the following code:
Run your code
Save this file to your machine and run it:
Prerequisites
Run your code
Save this file to your machine and run it:
Prerequisites
Create a file named send.rb and add the following code:
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.