API Connection Overview

There are two available interface options for customers to connect their applications to the Aerialink gateway for SMS messaging: the Aerialink REST API over HTTP, and the telecom-industry-standard protocol SMPP. Both run over IP.

Multiple resources are available via the RESTful API, such as Messages, Message Status, and Numbers Lookup, each accessed via a specific URI. While the SMPP protocol is used for only SMS, bear in mind that a single customer account can support separate HTTP and SMPP binds with multiple connection credentials.

HTTP

Because Aerialink’s REST API runs via HTTP, interfacing external applications with Aerialink requires only a simple network connection. REST is a lightweight alternative to mechanisms like RPC and web services (SOAP, WSDL), and greatly simplifies development. The API is platform-and-language-independent and is easily used with the Aerialink firewall via a set of API key and secret credentials.

• Use of SSL is supported and strongly encouraged.
• Request and response formats (JSON, XML) are specifiable.
• URL endpoints can be defined in a route action to receive inbound messages and carrier delivery notifications.

Use of Aerialink API assumes a working knowledge of HTTP components such as GET and POST request methods, response status code (200, 400, 404, etc.) and general use of RESTful web APIs. The transient connection mode allows a new connection to be made with every request.

SMPP

The Aerialink gateway supports SMPP (Short Message Peer to Peer) versions 3.3 and 3.4 to connect to our SMSC over TCP/IP.

SMPP is a level 7 TCP/IP protocol used to send SMS messages capable of delivering them at high speed as well as high volume, as it was specifically designed and optimized for the transmission of SMS messages and many mobile operators therefore provide SMPP connections for SMS traffic.

The most commonly used versions of SMPP are v3.3 and v3.4. Version 3.3 is the most widely supported with separate transmitter and receiver modes, while v3.4 has added support for transceivers (single connections that can send and receive messages).

While HTTP’s encoding is text-based, SMPP encodes its data into packets, which allows it to transfer more efficiently.

Data exchange is synchronous, where each peer must wait for a response for each PDU being sent. Aerialink will be supporting asynchronous exchange in the near future, where multiple requests can be issued in one go and acknowledged in a skew order by the other peer. When interfacing via the SMPP protocol, your application binds to our gateway with a persistent connection, which increases the speed of message delivery by allowing the bind to be kept live indefinitely, thereby eliminating the need to wait for responses when issuing requests. Development work is greatly reduced if you use a third-party application that supports SMPP.

SMPP Supports:

• Text, Unicode and flash messaging*
• Messages 160+ characters long
• Delivery acknowledgement
• All code/number types
• Two-way delivery

*Support varies by carrier

Choosing Your Connection API

We have encapsulated the key points described above (and then some) to help you carefully consider and choose which connection API will work best for your needs.

*Optional

+ Using a third-party SMPP library, or software with a built in SMPP client such as ActiveXperts, significantly reduces development time when interfacing with Aerialink.

Or, for a more direct comparison of perks, see this table:

Communications Protocols

Protocols, also known as “transport mediums,” are the language by which your message is delivered through each part of the mobile communications ecosystem.

Aerialink’s Connection Gateway supports the following wireless communication protocols:

• HTTP (JSON and XML Schemas)
• SMPP (3.3 and 3.4)
• MM4 (SMTP)
• SMTP

MM4 (SMTP)

MM4 is an SMTP based interface where the MMS message is posted to the server as a standard MIME encoded e-mail message. While the interface exists primarily for connectivity between multiple MMSCs, Aerialink also makes this interface available to application developers that are more comfortable with the SMTP protocol.

Message Processing

Phase 1: Customer Message Request

Opt-Out Status Check

Aerialink checks to see if the end-user has enforced an opt-out, in which case the message will be rejected with a response code of 52.

Gateway Acknowledgement

A transaction ID is generated the instant our network accepts the customer message for processing.

HTTP Status Code: 200

Along with your Gateway Acknowledgement response code of 10, 50, 51, 52 or 55 (as detailed below), you should receive an HTTP status code of 200, which confirms that the Aerialink network has processed the application request. If you receive any HTTP code aside from 200, please contact customer support.

Success & Error Codes

Successful submission will be met with a response of 10, 50, 51, 52 or 55. Erroneous submissions will be met with error codes in series 1000, 1010, 1020, 1030, 1040 or 1050. For more information on these, please refer to our API status codes document.

Phase 2: Carrier Status Response

Carrier Delivery Acknowledgement

A CDA denotes that a message has been received by the carrier and is being sent out to the mobile device. There are only six instances in which a successful CDA could still result in a failed message:

1. Destination number is a plausibly valid line range but is not active.
2. Improper format resulting in false country code recognition.
3. Destination device is part of a pre-paid service but has no funds.
4. End-User has not paid their service bill.
5. Destination number has opted out of receiving text messages.
6. Destination device is unable to receive the message within the validity period.

Status Code: 20 (Request Completed)

When the carrier confirms receipt of the message, our status will be updated to reflect this change. If this update fails upon the first attempt, it will retry ten times at intervals of one attempt per fifteen minutes. If a status code of 10 is received upon this check, then the status has not yet been updated.

Phase 3: Authentication & Validation

Carrier Delivery Receipt (DLR)

A DLR is a confirmation that the destination device has received the message, and is available if supported by the carrier. Read our Carrier Delivery Receipt article for more information about DLR.

Validity Period

During this time, the carrier will repeatedly attempt to send the message to the destination device. If the message fails due to a temporary reason (e.g., the mobile phone is turned off, the user is out of range) the carrier will continue to send until the destination handset receives the message or the validity period expires.