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, Locations 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.
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.
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, such as ActiveXperts.
- 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.
|API Connectivity Feature||HTTP REST API||SMPP API|
|Implementation||Simpler||Telecom protocol knowledge required +|
|Message Sent over||TCP/IP||TCP/IP|
|Transmission Method||GETPOST||TCP SocketSMPP Bind|
|Connection Type||Post to URL||3.3: Transmitter/Receiver3.4: Transceiver|
|Resources Supported*||SMSMMSMessage StatusLocations ServicesNumbers LookupLists||SMS|
+ 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:
|Most commonly used API||x|
|Connects only when traffic is received||x|
|Messages sent through web (HTTP)||x|
|Supports request/response formats in XML and JSON||x|
|Uses popular methods HTTP GET, POST, XML, SSL||x|
|Multiple Aerialink resources: SMS, MMS, Location, Numbers Lookup, List Management||x|
|Provides delivery receipts (DLR)||x||x|
|Synchronous or asynchronous data exchange||x|
|Experience with SMPP 3.3 or 3.4 specs required||x|
|High-volume bulk messaging recommended||x|
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)
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.
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.
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:
- Destination number is a plausibly valid line range but is not active.
- Improper format resulting in false country code recognition.
- Destination device is part of a pre-paid service but has no funds.
- End-User has not paid their service bill.
- Destination number has opted out of receiving text messages.
- 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 DLRs.
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.
This page was last updated 1515185923000