Retrieving SMS

Inbox

The Retrieve SMS API allows you to get all messages that have been sent to any of your Virtual Mobile Numbers.

Request

GET /inbox

OPTIONAL Properties

There are no required properties for this API, only optional

Attribute Type Description Default
keyword string Search by keyword used. This would be the first word in the body of the message.
start datetime, string The oldest date of the messages you want to retrieve.

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)
NOW()
end datetime, string The newest date of the messages you want to retrieve.

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)
from int The number the message was sent from
to int The number the message was sent to.
reference string If you used the external_reference parameter in the Send SMS API, then this will show in reference to that message
sort string Sort the response by ID in ASC or DESC order. DESC
skip int Where to start the returned results 0
limit int Where to end the returned results. Limit: 1000 25

Example Code

curl https://api.voodoosms.com/inbox \
  -H "Authorization: Bearer {key}"
<?php
    $api_key = 'API KEY';

    $ch = curl_init('https://api.voodoosms.com/inbox');

    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Authorization: ' . $api_key
    ]);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

    $response = curl_exec($ch);

    curl_close($ch);

Response

{
  "count": 2,
  "unread": 1,
  "message": [
    {
      "id": 46123,
      "from": 447860123858,
      "to": 447857475646,
      "nickname": "Pizza Guy",
      "msg": "Hi, yes I'd like a large pepperoni, please",
      "recievedDateTime": 1538611200,
      "external_reference": "Pizza Order: 333",
      "reply-to-id": "CL6Rt0ZwDcH5vMU"
    },
    {
      "id": 46134,
      "from": 447860126789,
      "to": 447857475646,
      "nickname": null,
      "msg": "Hi, yes I'd like a small BBQ chicken, please",
      "recievedDateTime": "2018-11-09T12:11:00+00:00",
      "external_reference": "Pizza Order: 688",
      "reply-to-id": "CL6Rt0ZwDcH5vMU"
    }
  ]
}

Errors

Code Message Meaning
30 You have no messages in your inbox Your Inbox is empty

Error Response

{
  "error": {
    "code": 30,
    "msg": "You have no messages in your inbox"
  }
}

Delete Messages

Delete messages in your Inbox

Request

DELETE /inbox/:id

Example Code

curl -X DELETE https://api.voodoosms.com/inbox/46134 \
  -H "Authorization: Bearer {key}"
<?php
$api_key = 'API KEY';

$ch = curl_init('https://api.voodoosms.com/inbox/46134');

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": "Inbox message ($id) has been removed"
}

Error Response

{
  "error": {
    "code": 36,
    "msg": "Invalid ID"
  }
}

Numbers

Retrieve a list of your purchased Virtual Mobile Numbers. If you do not have a VMN, you can purchase one here.

Request

GET /numbers

Example Code

curl https://api.voodoosms.com/numbers \
  -H "Authorization: Bearer {key}"
<?php
$api_key = 'API KEY';

$ch = curl_init('https://api.voodoosms.com/numbers');

curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: ' . $api_key
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);

curl_close($ch);

Response

{
  "count": 2,
  "number": [
    {
      "id": 454,
      "number": 447860064555,
      "purchased": 1541603582,
      "nickname": "Homer Simpson",
      "next_payment": 1542813252
    },
    {
      "id": 455,
      "number": 447860064768,
      "purchased": 1541603582,
      "nickname": "Bart Simpson",
      "next_payment": 1493696723
    }
  ]
]

Properties

There are no required or optional properties for this API.

Errors

Code Message Meaning
31 You do not own any Virtual Mobile Numbers You have no VMN’s attached to your account.

Error Response

{
  "error": {
    "code": 31,
    "msg": "You do not own any Virtual Mobile Numbers"
  }
}

Keywords

Retrieve a list and manage your Keywords.

Retrieve Keywords

Retrieve a list of keywords assigned to your VMN’s.

Request

GET /keywords

OPTIONAL Properties

There are no required properties for this API, only optional

Attribute Type Description
keyword string The keyword you want to search for
assigned_to int A VMN where a keyword is assigned

Example Code

curl https://api.voodoosms.com/keywords \
  -H "Authorization: Bearer {key}"
<?php
$api_key = 'API KEY';

$ch = curl_init('https://api.voodoosms.com/keywords');

curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: ' . $api_key
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);

curl_close($ch);

Response

{
  "count": 1,
  "keywords": [
    {
      "id": 43,
      "keyword": "COLA",
      "assigned_to": 447860064345,
      "description": "The cola campaign to see who likes Cola",
      "created_at": 1523877180,
      "updated_at": 1526481843
    }
  ]
}

Error Response

{
  "error": {
    "code": 32,
    "msg": "You have no Keywords"
  }
}

Errors

Code Message Meaning
32 You have no keywords You have no keywords assigned to any of your numbers.
33 Invalid number You do not have access to this chosen number.

Add New Keyword

Create a new keyword and assign it to a number.

Request

POST /keywords

Properties

Attribute Type Description
keyword string The keyword you want to assign
assign_to int The number you want to assign the keyword to

Example Code

curl -X POST https://api.voodoosms.com/keywords \
  -H "Authorization: Bearer {key}" \
  -d '{
    "keyword": "BOOK1",
    "assign_to": 447860064596
  }'
<?php
$api_key = 'API KEY';

$msg = json_encode(
    [
        'keyword' => 'BOOK1',
        'assign_to' => 447860064596
    ]
);

$ch = curl_init('https://api.voodoosms.com/keywords');

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

{
  "id": 47,
  "status": "SUCCESS",
  "keyword": "BOOK1",
  "assigned_to": 447860064596
  }
}

Errors

Code Message Meaning
34 Keyword already assigned to this number The keyword has already been assigned to the VMN.
35 Number not found The VMN chosen is not associated with your account.

Error Response

{
  "error": {
    "code": 34,
    "msg": "Keyword already assigned to this number"
  }
}

Delete Keyword

Delete a keyword from your account

Request

DELETE /keywords/:id

Example Code

curl -X DELETE https://api.voodoosms.com/keywords/47 \
  -H "Authorization: Bearer {key}"
<?php
$api_key = 'API KEY';

$ch = curl_init('https://api.voodoosms.com/keywords/47');

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",
  "message": "Keyword "keyword.name" has been deleted"
}

Errors

Code Message Meaning
23 Invalid ID The ID does not match any of your keywords

Error Response

{
  "error": {
    "code": 23,
    "msg": "Invalid ID"
  }
}