Scribd
Upload
173 views

Alienics HTTP API

Alienics provides an API to send and receive SMS messages globally. The API documentation outlines how to authenticate, specify message parameters like sender/recipient, and receive response codes. It describes sending text, binary, and multimedia messages and receiving delivery receipts with status updates.

Uploaded by

Boban Pavloski Bobio
Copyright
© © All Rights Reserved
Available Formats
Download as DOC, PDF, TXT or read online on Scribd
173 views

Alienics HTTP API

Alienics provides an API to send and receive SMS messages globally. The API documentation outlines how to authenticate, specify message parameters like sender/recipient, and receive response codes. It describes sending text, binary, and multimedia messages and receiving delivery receipts with status updates.

Uploaded by

Boban Pavloski Bobio
Copyright
© © All Rights Reserved
Available Formats
Download as DOC, PDF, TXT or read online on Scribd
You are on page 1/ 10

Alienics Inc.

HTTP API Documentation

[email protected] |
Confidential

Alienics Inc.2

SMS API
Alienics makes it simple to send and receive a high volume of SMS anywhere in the
world within minutes.
Alienics's SMS API allows you to:
- Send outbound messages to people in over 240 countries.
- Receive inbound messages to 240 countries.
- Receive handset delivery receipts to most countries.

Request
Base URL
All requests to Alienics must be submitted to the base URL. Alienics provides you with
an option of a response as a XML string - you get to choose which response by
selecting the appropriate base URL for your request.
XML end point
http://192.99.47.166/sms/xml

HTTP Methods
All requests are submitted through the HTTP POST or GET method using UTF-8
encoding and URL encoded values.

[email protected] |
Confidential

Alienics Inc.3

Authentication
All requests require your API credentials.
Parameter

Description

username

Required. Your username. Ex: username=alienics

password

Required. Your password. Ex: password=resume123

SMS Parameters
Parameter

from

to

type

Description

Required. Sender address may be alphanumeric (Ex: from=MyCompany20). Restrictions


may apply, depending on the destination.

Required. Mobile number in international format, and one recipient per request. Ex:
to=447525858444 or to=00447522486424 when sending to UK.

Optional. This can be omitted for text (default), but is required when sending a Binary
(binary), WAP Push (wappush), Unicode message (unicode), vcal (vcal) or vcard (vcard).

Required when type='text'. Body of the text message (with a maximum length of 3200
text

characters),UTF-8 and URL encoded value. Ex: "Dj vu" content would be "D%c3%a9j
%c3%a0+vu"

[email protected] |
Confidential

Alienics Inc.4

Parameter

delivery-receipt

message-class

Description

Optional. Set to 1 if you want to receive a delivery report (DLR) for this request. Make sure to
configure your "Callback URL" in your "API Settings"

Optional. Set to 0 for Flash SMS.

Specific Parameters for Binary message

body

Required. Hex encoded binary data. Ex: body=0011223344556677

udh

Required. Hex encoded udh. Ex: udh=06050415811581

Alienics supports Unicode for multiple language support. Text length, however, is limited
to 70 characters-exceeding 70 characters will have your message split into parts.
Further, the mobile device must support the character encoding, for example, a US
device may not display Arabic.
In the event your text is longer than 160 characters, Alienics will split the message into
parts. Alienics's response, in that case, will tell you how many parts the message has
been sent in. Eg:
curl "http://192.99.47.166/sms/xml?
username=yourusername&password=yourpassword&from=MyCompany20&to=447525856424&t
ext=D%c3%a9j%c3%a0+vu"

[email protected] |
Confidential

Alienics Inc.5

Response
After submitting a request to the Alienics API, you will receive an HTTP response and a
delivery receipt to your callback URL (if you have indicated one in your API settings).
The HTTP response will contain XML string, depending on the base URL you chose to
submit your request, and will indicate the success or failure for your request on the
Alienics platform. The actual delivery status of the message, however, is only confirmed
by the delivery receipt.

XML response
<?xml version='1.0' encoding='UTF-8' ?>
<mt-submission-response>
<messages count='x'>
<message>
<messageId>${messageId}</messageId>
<to>${to}</to>
<status>${returnCode}</status>
<errorText>${error-message}</errorText>
</message>
</messages>
</mt-submission-response>

The tags and values returned in an XML response may contain the following:

Tag

Value

messages

Contains each message part, attribute "count" contains number of parts.

message

A single message part.

[email protected] |
Confidential

Alienics Inc.6

Tag

Value

status

The return code.

messageId

The ID of the message that was submitted.

errorText

If an error occurred, this will explain in readable terms the error encountered.

Response Examples
XML Successful response sent in three parts:
<?xml version='1.0' encoding='UTF-8' ?>
<mt-submission-response>
<messages count='3'>
<message>
<messageId>00000124</messageId>
<to>44123456789</to>
<status>0</status>
</message>
<message>
<messageId>00000125</messageId>
<to>44123456789</to>
<status>0</status>
</message>
<message>
<messageId>00000126</messageId>
<to>44123456789</to>
<status>0</status>
</message>

[email protected] |
Confidential

Alienics Inc.7

</messages>
</mt-submission-response>

XML Error response, sent in one part:


<?xml version='1.0' encoding='UTF-8' ?>
<mt-submission-response>
<messages count='1'>
<message>
<status>2</status>
<errorText>Missing from param</errorText>
</message>
</messages>
</mt-submission-response>

Response Codes
Code

Error Text

Meaning

Success

The message was successfully accepted for delivery by Alienics

Throttled

Missing params

Your request is incomplete and missing some mandatory parameters

Invalid params

The value of one or more parameters is invalid

Invalid credentials

The username / password you supplied is either invalid or disabled

Internal error

An error has occurred in the Alienics platform whilst processing this

You have exceeded the submission capacity allowed on this account,


please back-off and retry

[email protected] |
Confidential

Alienics Inc.8

Code

Error Text

Meaning

message

Partner quota exceeded

Your pre-pay account does not have sufficient credit to process this
message

Account not enabled for

This account is not provisioned for REST submission, you should use

REST

SMPP instead

Message too long

10

Invalid Message class

Applies to Binary submissions, where the length of the UDH and the
message body combined exceed 140 octets

The message class value supplied was out of range (0 - 3)

Delivery Receipt
During account set-up, you will be asked to supply Alienics, CallBack URL for Delivery
Receipt to which we will send a delivery receipt for each of your SMS submissions. This
will confirm whether your message reached the recipient's handset. The request
parameters are sent via a GET (default) to your Callback URL and Alienics will be
expecting response 200 OK response, or it will keep retrying until the Delivery Receipt
expires (up to 72 hours).

The Alienics delivery receipt request includes the following parameters.

[email protected] |
Confidential

Alienics Inc.9

Parameter

Value

messageId

Message ID.

status

Status of message.

err-code

Status related error code.

Time when the dlr was received from mobile operator. In format
message-timestamp

yyyyMMddHHmmss

Status parameters will be of the following possible values:

Status

Meaning

Delivered

Message arrived to handset.

Expired

Message timed out after we waited 48h to receive status from mobile operator.

Undeliverable

Message failed to be delivered.

Rejected

Message has been rejected by the mobile operator.

Accepted

Message has been accepted by the mobile operator.

[email protected] |
Confidential

Alienics Inc.10

Status

Meaning

Deleted

Message has been deleted.

Unknown

Undocumented status from the mobile operator.

[email protected] |
Confidential

You might also like