Introduction

Welcome to the VoodooSMS API. Our API allows you to integrate your website or your application to our platform giving you the ability to use our features such as our Send SMS API.

Our API is built and maintained internally. Unlike other providers, if you require custom, or bespoke API work then we are able to explore this as an option. Please get in touch.

We use a RESTful endpoint with an API Key which is used to authorize the API.

Responses are returned as JSON.

All requests must be made over an SSL connection (https). If you are limited http, please get in touch.

Getting Started

To begin using the API you must first register a free account with VoodooSMS.

Once registered, please follow instructions below to create an API Key.

Authentication

Authentication using Bearer Authorisation header
curl https://api.voodoosms.com/credits \
  -H 'Authorization: Bearer {key}'

Authentication is done via an API Key. You can obtain your Key on the portal in Send SMS>API SMS>RESTful API.

Each API call sent through us will need to be authenticated using the Bearer authentication mode in the request headers of your application.

Message Body

When specifying the message body in the request, the characters used as well as the length of the message affect how many actual SMS messages are sent out, and the number of credits used.

1 SMS credit equals up to 160 characters. Messages above that length, will be broken down to multiple messages of 153 characters, costing 1 SMS credit each.

Supported Characters

The following characters if used will be sent as plain text 7-bit encoding which allows you to send an SMS up to 160characters before it is segmented into a ‘long message’:

@ Δ SP 0 ¡ P ¿ p
£ _ ! 1 A Q a q
$ Φ 2 B R b r
¥ Γ # 3 C S c s
è Λ ¤ 4 D T d t
é Ω % 5 E U e u
ù Π & 6 F V f v
ì Ψ 7 G W g w
ò Σ ( 8 H X h x
Ç Θ ) 9 I Y i y
LF Ξ * : J Z j z
Ø + ; K Ä k ä
ø Æ , < L Ö l ö
æ - = M Ñ m ñ
Å ß . > N Ü n ü
å É / ? O § o à
  • LF equals a newline (\n)
  • SP equals a space

There are some specific characters that when used will actually take up 2 characters on your message. These are known as ‘Extended-GSM’ characters and include:

| , ^ , , { , } , [ , ] , ~ , \

Long Messages using only 7-bit characters are multiples of 153 characters in length. See the section below that refers to Long Messages.

Other Characters (Unicode) 👀

If other characters are required for different languages, 16-bit Unicode (UCS-2) encoding will be used (including Emojis 😎).

When using UCS-2 encoding, each character will take 2 bytes, which means up to 70 characters can be sent per UCS-2 encoded SMS message.

Long Messages using only 16-bit (Unicode) characters are multiples of 67 characters in length. See the section below that refers to Long Messages.

Long Messages

This refers to a message that exceeds 160 standard characters, or 70 Unicode characters.

The tables below will give you a visual idea of how your messages will be segmented depending on the characters used within the SMS body:

7-bit (Standard Characters)

Length Segments
1 - 160 1
161 - 306 2
307 - 459 3
460 - 612 4
613 - 765 5
766 - 918 6

Long messages using standard characters are sent in a multi-part 7-bit encoded message and has a maximum character limit of 153.

16-bit (Unicode Characters including Emojis)

Length Segments
1 - 70 1
71 - 134 2
135 - 201 3
202 - 268 4
269 - 335 5
336 - 402 6

Long messages using Unicode characters are sent in a multi-part 16-bit encoded message and has a maximum character limit of 67.

Click here for a guide on how to use Emojis from your computer

Endpoint

https://api.voodoosms.com/

Sandbox

The sandbox parameter allows you to use our Send SMS API without any actions been taken.

Example Code

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",
    "sandbox": true
  }'

PHP

<?php
api_key = 'API KEY';

msg = json_encode(
    [
        'to' => 447133875699,
        'from' => "VoodooSMS",
        'msg' => "This is another test message",
        'schedule' => "3 weeks",
        'external_reference' => "Testing VoodooSMS",
        'sandbox' => true
    ]
);

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);
Example Response
{
  "count": 1,
  "originator": "VoodooSMS",
  "body": "Hello this is a test",
  "scheduledDateTime": null,
  "credits": 1,
  "balance": 2365,
  "messages": [
    {
      "id": null,
      "recipient": 447800000000,
      "reference": null,
      "status": "SANDBOX"
    }
  ]
}

How To Use

Add the sandbox parameter alongside your other parameters and mark it as true .

When using this API with the sandbox parameter, you will receive a response back as normal, but the actual SMS will not be sent.