Overview

API Interface: HTTPS
Resource: Send and Receive SMS
URI: /v4/messages
Methods: POST
Response Schemas: JSON (default), XML

An application programming interface for connecting external applications, systems, and devices with the Aerialink Service Gateway for the purpose of sending and/or receiving SMS (Text Messages), MMS (Multimedia Messages), or Data (Binary) content between an application service and a mobile wireless handset or device operating on any approved wireless carrier. This specific API covers SMS & messages only.

Outbound (MT) Message Response Schema

When sending an outbound (MT) message, you will receive a response from the API. Aerialink supports both JSON and XML response schemas, however the default response schema is JSON. If you wish to receive your response schema in XML or explicitly set the response schema to JSON, follow these examples as you construct your complete request URL.

/messages
(defaults to JSON automatically)

/messages.json
(explicitly sets the response to a JSON schema, same as default)

/messages.xml
(sets the response to an XML schema)

Inbound (MO) Message Forwarding

Please note that inbound message forwarding can either take the form of a GET query string parameter or POST URL-encoded form data.

Method [POST] : Sending an SMS

This method sends an SMS message from your application through the Aerialink Gateway to the destination number. The request is initiated by your application.

Request

The available request parameters for this resource and method are listed below and should be sent form-post.

Required Parameters

• source [string(15)]
  The source code for the message. This must match to one of your codes associated with your connection.

• destination [string(15)]
  The destination number that you want to send the SMS message to. Aerialink accepts almost any format while in “friendly format” mode (see the parameter destinationFormat below). The recommendation for US based numbers is the 11 digit format: “13105551212”.

• messageText [string(160)]
  The SMS message text that you are sending to the end user handset device. This is limited to the general standard of 160 characters unless concatenation is enabled on your account. In some cases your character limit may be less depending on your specific use case and configuration or a carrier limitation.

Optional Parameters

• destinationFormat [integer]
  Defaults to 0 for “friendly format” which is the default. If this parameter is passed with a value of 1 then Aerialink will expect the destination number in “international format” with the country code (ex. “xXXXxxxXXXX”). This is required for any international messaging.

• registeredDelivery [integer]
  Defaults to 0. If set to 1, this will request a delivery receipt from the carrier which will be delivered to the URL that you specify in your account configuration.

• destinationPort [string(10)]
  Use this parameter when you need your MT (mobile terminate) SMS to be directed to a specific port on the mobile handset device. This parameter should not be passed when sending standard SMS Text messages that are intended for the end user to read.

• programID [string(25)]
  This parameter is required for some short codes and is handled by Aerialink on the backend, where we configure it to the code and pass it to the carrier. Therefore, it does not need to be included in the calls sent by customers to Aerialink.

• dcs [integer]
  Use this to specify the character set that should be used for the message. Defaults to 0 for the SMSC alphabet. Refer to the Data Coding Scheme page for supported DCS values.

Response (Synchronous)

Response Properties

The parameters or elements returned in the response to an API request.

• version : The requested version of the resource
• resource : The requested resource name
• method : The method for the request. This will always be one of the following; GET, POST, UPDATE, DELETE
• type : The request type; Syncronous or Asyncronous
• transactionGUID : The globally unique transaction ID for the message
• destination : Operating company directory number

Response Schema

JSON Format(default schema)

{
  "aerialink": {
    "version": "v4",
    "resource": "messages",
    "method": "post",
    "type": "synchronous",
    "transactions": [
      {
        "transaction": {
          "transactionGUID": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
          "destination": "12223334444"
        }
      }
    ]
  }
}

XML Format

<?xml version="1.0" encoding="UTF-8"?>
<aerialink>
 <version>v4</version>
 <resource>messages</resource>
 <method>post</method>
 <type>synchronous</type>
 <transactions>
  <transaction>
  <transactionGUID>XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX</transactionGUID>
  <destination>12223334444</destination>
  </transaction>
 </transactions>
</aerialink>

Method [POST] : Receiving an SMS

This method is used by Aerialink to deliver SMS from an end-user device to your application. The request is initiated by Aerialink

Request

Send the following request parameters form-post via an HTTP POST to the URL that you have defined in your connection/route. This can be configured or modified within the Aerialink Platform Portal.

Parameters

• transactionGUID [string(36)]
  The globally unique transaction ID for the message.

• connectionGUID [string(36)]
  The globally unique identifier for the Aerialink network connection in your account which processed the transaction.

• source [string(15)]
  The source address for the message. This is the end user mobile phone which sent you the message.

• sourceCountry [string(255)]
  The registered country name for the number.

• sourceCountryCode [integer]
  The associated country code for the number.

• sourceCountryAbbreviation [string(2)]
  The two-letter country abbreviation (ISO 3166-1 alpha-2)

• destination [string(15)]
  The destination number that the end user sent the message to. This will match with a Short/Long Code configured on your account.

• messageText [string(160)]
  The SMS message text that the end user sent to your Short/Long Code. This is limited to the general standard of 160 characters unless concatenation is enabled on your account. In some cases your character limit may be less depending on your specific use case and configuration or a carrier limitation.

• concatenatedMessage [string(5)]
  true/false

Optional Parameters

• sourceNational [string(15]
  The source address for the message in national format, excluding the country code. This is the end user mobile phone which sent you the message.

• udh [string(25)]
  Variable length defined inside the UDH itself

• concatenatedMessageReference [string(5)]
  The message reference for a given concatenated message group. Under most circumstances this value will be either 8 or 16 bit HEX value, but for compatibility reasons should be treated as a string(5).

• concatenatedMessageSegments [string(2)]
  The total number of segments for a given concatenated message, provided in 8-bit HEX value.

• concatenatedMessageSegmentNumber [string(2)]
  The specific message segment number for a given set of segments related to a concatenated message, provided in 8-bit HEX value.

• concatenatedMessageSegmentHash [string(64)] - Important Note: This parameter will only be available on or after June 25, 2016.
  A unique SHA-256 hash that represents the source, destination, message text, total segments, and segment number for the specific segment of a concatenated message. This data can be used to validate a message without requiring an analysis of actual message content which may be restricted by customer privacy laws.

Response (Synchronous or Aynchronous)

Aerialink expects to receive an HTTP status code of 200 from your application server which confirms your receipt of the HTTP POST. If we do not receive this HTTP status code our network will continue to retry the callback to your application until the pre-defined expiration period.

Method [GET] : Retrieving an SMS

This method retrieves an inbound end-user message from Aerialink. The request is initiated by your application.

NOTE:

• The use of this method requires special approval.
• The frequency of API requests to this resource using this method should be limited to no more than one request per minute. If your application requires more real-time processing, we strongly recommend that you implement the POST method initiated by Aerialink rather than this GET retrieve method.
• Messages older than 24 hours are subject to expiration if they are not retrieved.

Request

The available request parameters for this resource and method are listed below and should be sent form-post.

Optional Parameters

• maxRows [integer]
  The maximum number of rows that you wish to be returned in the response from your request. The default is 10 and the maximum value is 500.

Response (Synchronous or Aynchronous)

Aerialink will return an HTTP(s) status code in the 200 range upon a successful request along with the following response details. The 200 range could be any of the following values (200, 201, 202, 203, 204, 205, or 206) but in most all cases will be 200. If you do not receive one of these status codes in the response from us, your application should retry the HTTP(s) request at a later date or refer to the specific HTTP status code for more detail.

Response (Synchronous)

Response Properties

The parameters or elements returned in the response to an API request.

• version: The requested version of the resource
• resource: The requested resource name
• method: The method for the request. This will always be one of the following; GET, POST, UPDATE, DELETE
• type: The request type; Syncronous or Asyncronous
• connectionGUID: The globally unique connection ID for the message
• transactionGUID: The globally unique transaction ID for the message
• source: The source number or device that initiated the message
• destination: The destination Short Code, Long Code, or TEXT Number for the message
• messageText: The message text.
• esmClass: The message class. (0 = Standard, 4 or 8 = Delivery Receipt, see ESM Class for more details)
• concatenatedMessage: Indicates whether this message is a multipart concatenated message or not

Response Schema

JSON Format(default schema)

{
  "aerialink": {
    "version": "v4",
    "resource": "messages",
    "method": "get",
    "type": "synchronous",
    "transactions": [
      {
        "transaction": {
          "connectionGUID":"XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX”,
          “transactionGUID” : "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX”,
          “source” : "12223334444,
          “destination” : "12223334444",
          “messageText” : "The SMS message from Aerialink.”,
          “esmClass” : 0,
          “concatenatedMessage” : false
        }
      }
    ]
  }
}

XML Format

<?xml version="1.0" encoding="UTF-8"?>
<aerialink>
 <version>v4</version>
 <resource>messages</resource>
 <method>get</method>
 <type>synchronous</type>
 <transactions>
  <transaction>
  <connectionGUID>XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX</connectionGUID>
  <transactionGUID>12223334444</transactionGUID>
  <source>12223334444</source>
  <destination>12223334444</destination>
  <messageText>The SMS message from Aerialink.</messageText>
  <esmClass>0</esmClass>
  <concatenatedMessage>false</concatenatedMessage>
  </transaction>
 </transactions>
</aerialink>