Sending SMS

Sending Overview

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.

OPTIONAL PROPERTIES

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).

Single SMS

Send a single SMS to a single recipient.

Request

POST /sendsms

PROPERTIES

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);

Using Dynamic Data

Important Information
  • Dynamic Data only works on the sendsms methods
  • You are restricted to only using 7 dynamic fields in your data

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"
    }
  ]
}

Errors

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"
  }
}

Bulk SMS

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.

Request

POST /bulksms

Properties

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"
    }
  ]
}

Errors

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"
  }
}

WebSMS via API

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.

Request

POST /websms

PROPERTIES

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"
  }
}

Send SMS to Contact List

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.

Request

POST /sendtocontacts

PROPERTIES

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"
    }
  ]
}

Errors

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"
  }
}

Schedule SMS

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

Retrieve your scheduled SMS

Important Information This will only retrieve messages that have been scheduled using the sendSMS API. SMS scheduled using the Web SMS module will not be displayed.

Request

GET /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"
    }
  ]
}

Cancel

Allows you to cancel the scheduled SMS by providing ID.

Request

DELETE /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"
  }
}

International

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.

HOW TO USE

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.

ERRORS

Code Message Meaning
14 Cannot send to this country You are trying to send to a country that you do not have enabled.

Response Errors

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.