Voxox SMS API Developer Documentation

Follow

Quick Start

Overview

The VoxOx SMS REST API gives you the ability to:

  • Send SMS messages

You can send SMS messages using VoxOx’s REST API. To send a message, just make an HTTP POST or GET to our API with the body of the message and the phone number you want to send it to. This will return a message id which can later be used to track the status of the message.

  • Track SMS messages

You can track the status of the message at any time using the returned message id.


Since the API is based on REST principles, it's very easy to write and test applications. You can use your browser to access URLs, and you can use pretty much any HTTP client in any programming language to interact with the API.

Outbound SMS

Base URL

Our API can be consumed over HTTP or HTTPS for increased privacy.

Base URL

http://api.sms.voxox.com

Methods

sendSms

Method URL

http://api.sms.voxox.com/method/sendSms/

Returns

SMS Message ID, json encoded. 

Type

Name

Default

Description

string

key

null

API Key

string

to

null

Message Destination Number

string

body

null

URL Encoded Message Body

boolean

utf8

false

Encode as UTF8. (true or false)

boolean

flash

false

Send as Flash SMS. (true or false)

Simple SMS Example URL

http://api.sms.voxox.com/method/sendSms/key/12345/to/18888888888/body/hello%20world

Flash SMS Example URL

http://api.sms.voxox.com/method/sendSms/key/12345/to/18888888888/body/hello%20world/flash/true

PHP + cURL Example

<?
  // Set Variables
  $smsUrl = "http://api.sms.voxox.com/method/sendSms";
  $key    = "12345";
  $to     = "18888888888";
  $body   = "Hi this is a test.";
  $body   = urlencode($body); // URL Encode Body 
// All HTTP POST Data $data="to={$to}&body={$body}&key={$key}"; // cURL. $ch = curl_init(); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_POST, 1); curl_setopt($ch, CURLOPT_POSTFIELDS, $data); curl_setopt($ch, CURLOPT_URL, $smsUrl); $result = curl_exec ($ch)or die(curl_error($ch)); curl_close ($ch); // API Returns everything json encoded, decode. $smsId = json_decode($result); echo $smsId; // Eg. (string) sms507c34327416e

getStatus

Method URL

http://api.sms.voxox.com/method/getStatus/

Returns

json encoded array with each status and timestamp. 

Type

Name

Default

Description

string

key

null

API Key.

string

smsId

null

Message ID generated by the sendSms method.

Example URL

http://api.sms.voxox.com/method/getStatus/key/12345/smsId/54321/

PHP Example

$status = json_decode(file_get_contents(“http://api.sms.voxox.com/method/getStatus/key/12345/smsId/54321”);

 

getStatusBulk

Method URL

http://api.sms.voxox.com/method/getStatusBulk/

Returns

json encoded array with each message’s statuses and timestamps.

Type

Name

Default

Description

string

key

null

API Key.

string

smsIdList

null

json encoded array with all smsIds to query.

Example URL

http://api.sms.voxox.com/method/getStatusBulk/key/12345/smsId/{54321,12345}/

PHP Example

$statusArray = json_decode(file_get_contents(“http://api.sms.voxox.com/method/getStatusBulk/key/12345/smsId/{54321,12345}”);

getHourCount

Method URL

http://api.sms.voxox.com/method/getHourCount/

Returns

json encoded integer.

 

Type

Name

Default

Description

type

name

default

description

Example URL

http://api.sms.voxox.com/method/getHourCount/key/12345/

PHP Example

$count = json_decode(file_get_contents(“http://api.sms.voxox.com/method/getHourCount/key/12345/”);

getDayCount

Method URL

http://api.sms.voxox.com/method/getDayCount/

Returns

json encoded integer.

Type

Name

Default

Description

type

name

default

description

Example URL

http://api.sms.voxox.com/method/getDayCount/key/12345/

PHP Example

$count = json_decode(file_get_contents(“http://api.sms.voxox.com/method/getDayCount/key/12345/”);

getWeekCount

Method URL

http://api.sms.voxox.com/method/getWeekCount/

Returns

json encoded integer.

Type

Name

Default

Description

type

name

default

description

Example URL

http://api.sms.voxox.com/method/getWeekCount/key/12345/

PHP Example

$count = json_decode(file_get_contents(“http://api.sms.voxox.com/method/getWeekCount/key/12345/”);

DLR Callback URL

You can configure your service with a callback URL to have DLR updates pushed to you, instead of having to query our API for a message status update.

This setting is configured in the management portal, under your account settings, DLR Callback URL.

A POST to this URL gets triggered once a message status of SMSC_ACK or a message status of SMSC_ERR is returned by our upstream providers.

The POST request will have a single parameter, called data, data is a JSON encoded array. The array will contain an entry for each step in the message’s life cycle. The first entry always contains the message’s envelope information.

Array Key Description

 

smsId

Internal identifier of the message, it’s used to track the message in our system

customerId

Your customer identifier

mo

Message Origination Number

mt

Message Termination Number

body

Body of the message

utf8

Is message UTF8 encoded?

flash

Is message a Flash SMS?

status

Status of the message. (HTTP_REQUEST, SMSC_SUBMIT, BILLED, SMSC_ACK, SMSC_ERR)

requestTimestamp

Timestamp in floating microseconds

rate

Rate at what the message was billed

details

Details returned by SMSC.

 

JSON Encoded Array Example

[
   {
      "smsId":"sms508f075e3a030",
      "customerId":"507f2a9186513",
      "mo":"16572016976",
      "mt":"18587366685",
      "body":"test",
      "utf8":"true",
      "flash":null,
      "status":"HTTP_REQUEST",
      "requestTimestamp":1351550814.2362
   },
   {
      "smsId":"sms508f075e3a030",
      "status":"SMSC_SUBMIT",
      "requestTimestamp":1351550815.2289
   },
   {
      "smsId":"sms508f075e3a030",
      "status":"BILLED",
      "rate":0.01,
      "requestTimestamp":1351550815.2304
   },
   {
      "smsId":"sms508f075e3a030",
      "status":"SMSC_ACK",
      "details":"ACK%2F",
      "requestTimestamp":1351550854.7268
   }

 

PHP Example

// Get last status of a message
$dataArray = jsondecode($_POST[‘data’],1);
$itemCount = count($dataArray);
$status = $dataArray[$itemCount][‘status’];
$statusTimestamp = $dataArray[$itemCount][‘requestTimestamp’];	

Inbound SMS

Overview

If you have SMS enabled DIDs, these will be automatically provisioned in our SMS Center. You can see the list of provisioned inbound SMS numbers in the SMS Portal.

All incoming messages destined to any of your provisioned numbers will be relayed to a predefined Callback URL in the form of a HTTP POST. This setting is configured in the management portal, under your account settings, Callback URL. Please refer to the SMSC Operational Manual for more information about configuring the Callback URL and querying for provisioned numbers.

 

Inbound Callback URL

A POST to the Callback URL gets triggered once a message destined to one of your DIDs is received by our SMS Center.

The POST request will have a single parameter, called data, data is a JSON encoded array. The array will contain the message envelope information and its contents.

Array Key Description

smsId

Internal identifier of the message, it’s used to track the message in our system

customerId

Your customer identifier

smscTimestamp

Timestamp of the message in the upstream gateway, in UNIX epoch timestamp format

mo

Message Origination Number

mt

Message Termination Number

body

Body of the message

coding

message coding: 0 (default, 7 bits), 1 (8 bits) or 2 (Unicode)

mclass

message class bits of DCS: 0 (directly to display, flash), 1 (to mobile), 2 (to SIM) or 3 (to SIM toolkit).

charset

message charset: for a "normal" message, it will be "GSM" (coding=0), "binary" (coding=1) or "UTF-16BE" (coding=2). If the message was successfully recoded from Unicode, it will be "WINDOWS-1252"

requestTimestamp

Timestamp in floating microseconds, UNIX epoch timestamp format.

 

JSON Encoded Array Example

[
   {
      "smsId":"sms508f075e3a030",
      "customerId":"507f2a9186513",
      "smscTimestamp":1351550814
      "mo":"16572016976",
      "mt":"18587366685",
      "body":"test",
      "coding":0,
      "mclass":1,
      "charset":"UTF8",
      "requestTimestamp":1351550814.2362
   }
]	

 

PHP Example

// Get message
$dataArray = jsondecode($_POST[‘data’],1);
$body      = $dataArray[‘body’];
Have more questions? Submit a request

Comments