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

Single SMS

Send a single SMS to a single recipient.

Request

PROPERTIES

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

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.

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

Properties

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.

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

PROPERTIES

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

PROPERTIES

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.

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

Request

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

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

Response Errors

These errors are universal to all Sending SMS API calls.