Retailer magic: SMS strategies for Winter | On Demand Sign up for our webinar
The Send SMS API allows you to send SMS to single or multiple recipients, or a contact list of numbers.
SMS can be sent straight away or scheduled for a date in the future.
Attribute | Type | Description | Default |
---|---|---|---|
dynamic_data | object | Supply dynamic data that can be used within’ your messages. This is the same functionality as adding dynamic data into your Contact Lists and using them in a Web SMS. | |
country_code | int | The country code for your destination number. | |
schedule | datetime,string | A date or time in the future to schedule SMS to be sent at. Formats: UNIX: A UNIX timestamp (e.g. 1537525884) ISO 8601: A string format including the time and timezone (e.g. 2018-02-22T09:03:00+00:00) Human Readable: A human readable way to write the date or time you want to sent the message at (e.g. 25th December 2019 21:00, 2 weeks, august 20, may 11 2019, last friday of march 2019, next saturday). | |
timezone | string | Match your timezone you’re sending from. Note: Will only work in conjunction with the schedule parameter. | UTC |
truncate | int | Select whether you want to truncate the from attribute. Value must be 1. | 0 |
quiet | int | Quiet times are set-up in the Portal in Settings>Quiet Times. Set-up your desired times and then you can enable this feature. Value must be 1. | |
validity | int | The amount of minutes the message is valid for. | 2880 |
external_reference | string | Your own reference for the SMS (e.g. An order number). |
Send a single SMS to a single recipient.
/sendsms
Attributes | Type | Description |
---|---|---|
to | string | The recipient of the SMS. |
from | string | Who the message is from. Can be a number or alphanumeric string. |
msg | string | The message you want to send. |
Code Example
cURL
curl -X POST https://api.voodoosms.com/sendsms \
-H "Authorization: Bearer {key}" \
-d '{
"to": 447000123890,
"from": "VoodooSMS",
"msg": "Testing The API",
"schedule": "3 weeks",
"external_reference": "Testing VoodooSMS"
}'
PHP
<?php
$api_key = 'API KEY';
$msg = json_encode(
[
'to' => 447133875699,
'from' => "VoodooSMS",
'msg' => "This is another test message",
'schedule' => "3 weeks", // Optional
'external_reference' => "Testing VoodooSMS" // Optional
]
);
$ch = curl_init('https://api.voodoosms.com/sendsms');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Authorization: ' . $api_key
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, $msg);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
Dynamic data is similar to how it is used when you add custom data into a Contact List and use that data in your Web SMS campaigns by supplying them in curly braces, e.g. {first name}
.
To start using dynamic data, you must supply a new dynamic_data
object as a parameter and then create your own custom data.
When writing out the message body in the msg
parameter, you can add your dynamic data by wrapping the objects’ key around curly braces. The content should match the same key as used in your object, otherwise it will throw an error.
Dynamic Data Object Example
{
"dynamic_data": [
{
"first name": "Peter",
"surname": "Griffin",
"age": "48",
"sex": "Male",
"colour": "Orange",
"band": "KISS",
"food": "Pizza"
}
],
// To use these, use them in the 'msg' param like so:
"msg": "Hello {first name}, I see you are {age} years old and enjoy eating {food}"
}
Response
{
"count": 1,
"originator": "VoodooSMS",
"body": "Hello Peter, I see you are 48 years old and enjoy eating pizza",
"scheduledDateTime": 1537525949,
"credits": 1,
"balance": 2365,
"messages": [
{
"id": "97709216074987x3NFD16GgkChK2E67441209181vapi",
"recipient": 447800000000,
"reference": null,
"status": "PENDING_SENT"
}
]
}
These errors are specific to this API call. More sendSMS
errors are available below.
Code | Message | Meaning |
---|---|---|
7 | Multiple destinations attempted | You can only send to one number per call. If you want to send bulk SMS, use the Bulk SMS API call. |
8 | Attempted to send to a contact list | To send to a Contact List of numbers, you must use the Send SMS to Contact List API. |
Error Response
{
"error": {
"code": 5,
"msg": "A required parameter is missing"
}
}
Send a message to multiple contacts in one go.
Similar to sending to a single contact but just provide a comma-separated list of numbers.
/bulksms
Attribute | Type | Description |
---|---|---|
to | array | The recipients of the SMS. |
from | string | Who the message is from. Can be a number or alphanumeric string. |
msg | string | The message you want to send. |
Code Example
cURL
curl -X POST https://api.voodoosms.com/bulksms \
-H "Authorization: Bearer {key}" \
-d '{
"to": "447000000123,447800000345",
"from": "VoodooSMS",
"msg": "Hello this is a test to multiple numbers"
}'
PHP
<?php
$api_key = 'API KEY';
$msg = json_encode(
[
'to' => "447700900123,447700900321",
'from' => "VoodooSMS",
'msg' => "This is a test message for multiple users",
'schedule' => "3 weeks", // Optional
'external_reference' => "Testing VoodooSMS" // Optional
]
);
$ch = curl_init('https://api.voodoosms.com/bulksms');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Authorization: ' . $api_key
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, $msg);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
Response
{
"count": 2,
"originator": "VoodooSMS",
"body": "Hello this is your SMS body to multiple contacts",
"scheduledDateTime": null,
"credits": 2,
"balance": 2363,
"messages": [
{
"id": "96889234412987x3NFD16GgkChK4R57441409423vapi",
"recipient": 447000000123,
"reference": null,
"status": "PENDING_SENT"
},
{
"id": "96899216074955x3NFD14GgkChK2E61267209599vapi",
"recipient": 447800000345,
"reference": null,
"status": "PENDING_SENT"
}
]
}
These errors are specific to this API call. More bulkSMS
errors are available here.
Code | Message | Meaning |
---|---|---|
9 | Attempted to send to a single destination | You must send to > 1 destination. If you want to send a single SMS, use the Bulk SMS API call. |
8 | Attempted to send to a contact list | To send to a Contact List of numbers, you must use the Send SMS to Contact List API. |
Error Response
{
"error": {
"code": 9,
"msg": "Attempted to send to a single destination"
}
}
To use WebSMS via API you will need to first configure this option within the portal, available here.
Once there, select Enabled under Please configure this section to allow to collect files when told to via an inbound API call and then choose between HTTPS or SFTP access.
If you require the IP addresses to allow access through a firewall that will be used, please contact support for the latest list.
Once the portal is configured, you can initiate a WebSMS via the API using a contact list supplied by SFTP / HTTPS.
/websms
Attribute | Type | Description |
---|---|---|
name | string | The name of the WebSMS used in reporting. |
from | string | Who the message is from. Can be a number or alphanumeric string. |
name | string | The filename that will be collected from the HTTPS or SFTP location. |
countrycode | int | The country code for your destination numbers, only one country code per file is allowed. |
static | string | The message you want to send. |
Code Example
cURL
curl -X POST https://api.voodoosms.com/websms \
-H "Authorization: Bearer {key}" \
-d '{
"name": "First WebSMS via API",
"from": "VoodooSMS",
"contacts": {
"file": {
"name": "./somefolder/anotherfolder/contactlist.csv",
"country_code": "44"
}
},
"static_msg": "This is my first WebSMS via API"
}'
PHP
<?php
$api_key = 'API KEY';
$msg = json_encode(
[
'name' => "First WebSMS via API",
'from' => "VoodooSMS",
'contacts' => [
'file' => [
'name' => './somefolder/anotherfolder/contactlist.csv',
'country_code' => '44'
],
],
'static_msg' => "This is my first WebSMS via API"
]
);
$ch = curl_init('https://api.voodoosms.com/websms');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Authorization: ' . $api_key
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, $msg);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
Response
{
"campaignId": 999999,
"campaignName": "First WebSMS via API",
"originator": "VoodooSMS",
"static": "This is my first WebSMS via API",
"dynamic": "",
"sentAt": 1594613872,
"messages": [{"status": "ACCEPTED"}],
"webSmsLink": "https://www.voodoosms.com/portal/reports/view_reports/999999"
}
HTTPS Code Example
curl -X POST https://api.voodoosms.com/websms \
-H "Authorization: Bearer {key}" \
-d '{
"name": "First WebSMS via API",
"from": "VoodooSMS",
"contacts": {
"file": {
"name": "https://www.exampleurl.com/somefolder/sample.csv",
"country_code": "44"
}
},
"static_msg": "This is my first WebSMS via API"
}'
Error Response
{
"error": {
"code": 5,
"msg": "A required parameter is missing"
}
}
You can send SMS to recipients off a Contact List.
You need to create a Contact List on the VoodooSMS Portal and import your numbers. Then using just the ID
you can send SMS to that list of numbers.
You can find the Contact List ID by going here and clicking the drop-down on your list, in the ID column.
/sendtocontacts
Attribute | Type | Description |
---|---|---|
to | string | A Contact List ID using the prefix of c, e.g. c4767. |
from | string | Who the message is from. Can be a number or alphanumeric string. |
msg | string | The message you want to send. |
Code Example
cURL
curl -X POST https://api.voodoosms.com/sendtocontacts \
-H "Authorization: Bearer {key}" \
-d '{
"to": "c4767",
"from": "VoodooSMS",
"msg": "Hello I am sending from a Contact List"
}'
PHP
<?php
$api_key = 'API KEY';
$msg = json_encode(
[
'to' => "c51396",
'from' => "VoodooSMS",
'msg' => "This is a test message to contact list",
'schedule' => "3 weeks", // Optional
'external_reference' => "Testing VoodooSMS" // Optional
]
);
$ch = curl_init('https://api.voodoosms.com/sendtocontacts');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Authorization: ' . $api_key
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, $msg);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
Response
{
"count": 25,
"originator": "VoodooSMS",
"body": "Hello I am sending SMS from a list of Contacts",
"scheduledDateTime": 1537525949,
"credits": 2,
"balance": 2363,
"messages": [
{
"id": "96889234412987x3NFD16GgkChK4R57441409423vapi",
"recipient": 447000000123,
"reference": null,
"status": "PENDING_SENT"
},
{
"id": "96899216074955x3NFD14GgkChK2E61267209599vapi",
"recipient": 447800000345,
"reference": null,
"status": "PENDING_SENT"
}
]
}
The errors below are unique to this API call. For additional sendToContacts
errors that may occur, can be found here.
Code | Message | Meaning |
---|---|---|
11 | Attempted to send to a specific destination | You cannot send to single or bulk numbers on this API call. |
12 | Invalid destination | You must prefix your Contact List ID with a c followed by the ID of your list. |
13 | Invalid contact list ID | The contact list ID you specified is not valid or does not belong to your account. |
Error Response
{
"error": {
"code": 13,
"msg": "Invalid contact list ID"
}
}
If you want to schedule your SMS to go out at a date in the future, add the schedule
parameter with a value of the date/time you want the SMS to go out. You can do this by using the Send SMS API. Dates can be in a UNIX timestamp or in the ISO 8601 format. See the SMS Overview for more details.
Retrieve your scheduled SMS
sendSMS
API. SMS scheduled using the Web SMS module will not be displayed./schedule
Code Example
cURL
curl https://api.voodoosms.com/schedule \
-H "Authorization: Bearer {key}"
PHP
<?php
$api_key = 'API KEY';
$ch = curl_init('https://api.voodoosms.com/schedule');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Authorization: ' . $api_key
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
Response
{
"count": 25,
"schedules": [
{
"id": 45678,
"originator": "VoodooSMS",
"body": "This is an SMS",
"scheduledDateTime": 15676789,
"status": "scheduled"
}
]
}
Allows you to cancel the scheduled SMS by providing ID.
/schedule/:id
Code Example
cURL
curl -X DELETE https://api.voodoosms.com/schedule/45678 \
-H "Authorization: Bearer {key}"
PHP
<?php
$api_key = 'API KEY';
$ch = curl_init('https://api.voodoosms.com/schedule/45678');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Authorization: ' . $api_key
]);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "DELETE");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
Response
{
"status": "SUCCESS",
"msg": "Scheduled SMS ($id) has been cancelled"
}
Error Response
{
"error": {
"code": 23,
"msg": "Invalid ID"
}
}
You can send SMS to International destinations, however, each country has different prices and most countries have rules and regulations around sending SMS.
Please contact your account manager, or speak to us on Live Chat to discuss your International requirements.
You must add the country_code
parameter to your API call with the country code of the country you wish to send to. Then add the number to the to
parameter and your messages will send successfully.
Code | Message | Meaning |
---|---|---|
14 | Cannot send to this country | You are trying to send to a country that you do not have enabled. |
These errors are universal to all Sending SMS
API calls.
Code | Message | Meaning |
---|---|---|
5 | A required parameter is missing | One of the required parameters needed is missing. |
15 | Validity is > 2880 | A message can only be valid for a maximum of 48 hours. |
16 | No country code given. Add country code (eg. 44 ) to beginning of number, or add the country_code param (eg. country_code=44 ) | Your default country code is not set or you have not prefixed the country code to your destination number. |
17 | No destination number given | to field was left blank. |
18 | Invalid characters detected | Your message contains invalid characters that are not allowed. |
19 | Your account has been locked out | You may be locked out of your VoodooSMS account for reasons. You cannot use the API while your account is locked. Please contact your Account Manager to discuss your account. |
20 | This number - 447111111111 - is currently on a blacklist. | A number you’re trying to send to is on your blacklist. |
21 | You have no credits | You have run out of credits and cannot send any more SMS until you top-up. |
22 | You do not have enough credits | You don’t have enogh credits to send to the amount of recipients you’ve specified. e.g. you have 10 credits and are trying to send to 25 recipients. |
23 | Invalid ID | The scheduled SMS campaign ID is invalid. This is used in conjunction with Scheduling SMS. |
24 | Scheduled date provided is in the past | The scheduled SMS date/time you have given is in the past. Times and dates can only be in the future. |
25 | Message length has exceeded XXX characters | The message body cannot exceed 918 characters. Note: If a message contains Unicode, the message body cannot exceed 402 characters. |
26 | Invalid Sender ID | The Sender ID must be > 3 and <= 11 alphanumeric characters. |
27 | You have no scheduled messages to be sent | You haven’t scheduled any SMS to be sent out. |
28 | Parsed data is invalid | The human readable format you chose cannot be parsed correctly. |
29 | This message has already been sent and cannot be cancelled | If a message has already been sent then it can no longer be cancelled. |
79 | Maximum dynamic data fields reached | The maximum amount of dynamic fields (7) has been exceeded. |
80 | Your dynamic data is invalid | Your data object may be formatted incorrectly, or the fields do not match up. |