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 an account with VoodooSMS. You can do that here.

Once registered, you must create an API Key. Click here to get further details on how to get this.

Authentication

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

Authentication is done via an API Key. You can obtain your Key here

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.

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.