AerFrame – Device Communication and Control API

What’s Here?

This page describes the full set of AerFrame™ APIs. A hands-on tutorial is available at Send/Receive SMS with AerFrame API.

Summary

AerFrame Short Message Service (SMS) APIs provide next-generation SMS messaging. AerFrame is designed for high performance and improved flexibility, allowing for fast and efficient data transmission to and from devices across the Aeris network.

Supported Operations

  • Send MT-SMS
  • Receive MT-SMS Delivery Notifications
  • Receive MO-SMS
  • Acknowledge MO-SMS Receipt

Features & Benefits

  • The SMS API is based on the OMA-DM standard SMS API
  • All AerFrame services are simple RESTful interfaces for rapid and simplified development
  • All AerFrame services are securely protected by API keys under customer control
  • The API for resetting network registration can be a powerful tool for resolving device connectivity issues
  • The API for getting a local dial-able number allows customers to deploy devices securely with non-dial-able numbers but still reach them when needed

API Overview

AerFrame includes the following set of APIs:

  • SMS Messaging API – derived from OMA Restful Short Messaging API. The outbound (MT) SMS delivery info and inbound (MO) SMS are delivered to applications over Notification Channels.
  • Notification Channel Management API – derived from OMA Notification Channel API. To receive MO SMS and delivery info for the MT SMS, applications must register themselves and setup a notification channel. All messages are delivered over Notification Channel. This version of AerFrame supports only the LongPoll Notification Channel.
  • The Network Service API – provides access to operations like Clear Registration and Get Local Dialable Number.

API Request, Headers, and Parameters

  • AerFrame APIs are available only over HTTPS.
  • Each API access must include the appropriate API Key in the request URL as shown in examples. The parameter name is “apiKey”.
  • All API must include Content-Type header with value application/json.

BASE URLS

The URL addresses for the production services are shown in Table 1, “AerFrame Base URLs”.

Base URL Purpose
https://api.aerframe.aeris.com AerFrame WebService: Submitting MT SMS Request
  • Application Management
  • Notification Channel Management
  • Subscription Management
  • Network Services (Clear Registration and Get Local Dialable Number)
  • Submitting MT SMS Request
https://longpoll.aerframe.aeris.com Longpoll Service:
  • Support only long poll requests to fetch MO SMS and MT SMS Delivery Info notifications.

Table 1: AerFrame Base URLs

API Client Authentication

AerFrame uses API Keys to authenticate clients and applications. Each request must include the API Key as a query parameter in the URL. The API Key uniquely identifies an account and provides the account context to the APIs. The Service Profile Name can then be used to further classify multiple applications belonging to an account.

There are two (2) sets of API keys:

  • Account API Key – When an account is registered for the AerFrame API, it is assigned a unique API Key. This API key can be used to perform all operations except subscription management. Subscriptions belong to applications and are managed by applications.
  • Application API Key – When an application is registered under an account, it is assigned a unique API Key. This API key can be used to perform all operations except application management.

Important:

API Key / Account ID: API Keys are unique and secret. They must be saved securely and should be shared with authorized users or apps only. To obtain your Account ID and API Key, refer to the Send/Receive SMS with AerFrame API section.

Open Mobile Alliance Specification for SMS APIs

The AerFrame service interface is derived from the Open Mobile Alliance (OMA) Specification for SMS APIs (OMA-TS-REST_NetAPI_ShortMessaging-V1_0-20130219-C.pdf). The OMA RESTful Network API for Short Messaging V1.0 is a re-publication of the ParlayREST ShortMessaging API V 1.1 [ParlayREST_SMS] and is part of the suite of OMA RESTful Network APIs. Additionally, the latest version (v1.2.3) of the GSMA OneAPI SMS API is a subset of the OMA SMS API and uses the same resource structure and datatypes as defined in the OMA API Specification.

Application Management Operations

  • AerFrame APIs are available only over HTTPS
  • Each API access must include the appropriate API Key in the request URL as shown in examples. The parameter name is “apiKey”
  • All APIs must include Content-Type header with value application/json

Operation

Request URI

Description

POST

registration/v2/{accountId}/applications

Register a New Application.

GET

registration/v2/{accountId}/applications/{appId}

Get Registered Application.

GET

registration/v2/{accountId}/applications/{appId}

Get All Registered Applications.

DELETE

registration/v2/{accountId}/applications/{appId}

De-Register an Application.

Table 2: AerFrame API Operations

Name

Presence

Description

applicationName

Mandatory

A name that the client can use to identify the application.

applicationTag

Mandatory

A tag that clients may use to tag this application. AerFrame stores it as it is without modifying and is not used in any way.

description

Mandatory

A description about the application that the client can use to brief the application and what it is used for.

apiKey

Mandatory

Generated by the AerFrame and provided in the response. This key is used for authentication in the queryParam of the request URL of all other AerFrame services.

apiKeyLifetime

Optional

AerFrame ignores this property. An apiKey once created is valid for lifetime unless application is explicitly deleted.

resourceUrl

Mandatory

Generated by the AerFrame service and included in the response.

applicationShortName

Mandatory

The unique identifier of the application with in the given account.

Table 3: AerFrame Application Attributes

Notification Channel Management Operations

There are up to two (2) Notification Channels available per application, with up to ten (10) total Notification Channels available per account. Each message will live for seven (7) days in the Notification Channel.

Operation

Request URI

Description

POST

notificationchannel/v2/{accountId}/channels

Create New Notification Channel.

GET

notificationchannel/v2/{accountId}/channels/{channelId}

Get a Notification Channel.

GET

notificationchannel/v2/{accountId}/channels

Get All Notification Channels.

DELETE

notificationchannel/v2/{accountId}/channels/{channelId}

Delete a Notification Channel.

Table 4: Notification Channel Management Operations

Name

Presence

Description

clientCorrelator

Optional

A name that the client can use to identify the application.

applicationTag

Optional

A tag that clients may use to tag this application. AerFrame stores it as it is without modifying and is not used in any way.

channelType

Mandatory

A description about the application that the client can use to brief the application and what it is used for.

channelData

Mandatory

Generated by the AerFrame and provided in the response. This key is used for authentication in the queryParam of the request URL of all other AerFrame services.

channelLifetime

Optional

AerFrame ignores this property. An apiKey once created is valid for lifetime unless application is explicitly deleted.

callbackUrl

Mandatory

Generated by the AerFrame service and included in the response.

resourceUrl

Mandatory

The unique identifier of the application with in the given account.

Table 5: AerFrame Notification Channel Attributes

Name

Presence

Description

channelURL

Mandatory

Generated by AerFrame and provided in the response for LongPoll channel type.

maxNotifications

Optional

Defines the maximum number of notifications that may be delivered in a notification list. Default is 15. AerFrame will wait for these many notifications or 10 seconds whichever is earlier. Applications that need lower latency should explicitly set this value of a lower number.

type

Optional

AerFrame only supports "nc:LongPollingData".

Table 6: AerFrame Notification Channel Data

Subscription Management Operations

To get Inbound SMS and Outbound SMS delivery information, applications need to subscribe for notifications. If there is no corresponding subscription for inbound SMS messages they are held for seventy-two (72) hours with one (1) retry every twenty-four (24) hours to check if a valid subscription exist. After seventy-two (72) hours the messages are dropped. If there is no corresponding subscription for outbound SMS delivery info then they are dropped immediately.

Operation

Request URI

Description

POST

smsmessaging/v2/{accountId}/outbound/{applicationShortName}/subscriptions

Create New Outbound (MT) SMS Delivery Info Subscription.

GET

smsmessaging/v2/{accountId}/outbound/{applicationShortName}/subscriptions/{subscriptionId}

Get a Specific Outbound Subscription

GET

smsmessaging/v2/{accountId}/outbound/{applicationShortName}/subscriptions

Get All Outbound Subscriptions for a Given Profile.

DELETE

smsmessaging/v2/{accountId}/outbound/{applicationShortName}/subscriptions/{subscriptionId}

Delete a Specific Outbound Subscription.

POST

smsmessaging/v2/{accountId}/inbound/subscriptions

Create New Inbound (MO) SMS Subscription.

GET

smsmessaging/v2/{accountId}/inbound/subscriptions/{subscriptionId}

Get a Specific Inbound Subscription.

GET

smsmessaging/v2/{accountId}/inbound/subscriptions

Get All Inbound Subscriptions.

DELETE

smsmessaging/v2/{accountId}/inbound/subscriptions/{subscriptionId}

Delete a Specific Inbound Subscription.

Table 7: Subscription Management API Operations

Name

Presence

Description

callbackReference

Mandatory

Notification Endpoint. AeFrame provides LongPoll service to receive notifications. Hence, the only supported callbackReference is the AerFrame-provided LongPoll Notification Channel. The Client must first create a Notification Channel and pass the callback URL from the Notification Channel here. Push notifications will be supported in the future.

filterCriteria

Mandatory

Must specify ServiceProfile names as "SP:sp1,sp2,sp3" or "SP:*" to subscribe for all service profiles under the account.

clientCorrelator

Optional

A correlator that the client can use to tag subscription. Clients can use this to identify subscription and avoid duplicate subscriptions. AerFrame stores it as it is without modifying and is not used in any way.

resourceURL

Mandatory

Generated by the AerFrame service and included in the response. The URL identifies the newly created resource.

link

Optional

Not used by AerFrame.

Table 8: AerFrame Outbound DeliveryInfoSubscription

Name

Presence

Description

callbackReference

Mandatory

Notification Endpoint. AeFrame provides LongPoll service to receive notifications. Hence, the only supported callbackReference is AerFrame-provided LongPoll Notification Channel. The Client must first create a notification channel and pass the callback URL from Notification Channel here. Push notifications will be supported in the future.

destinationAddress

Mandatory

This is the applicationShortName that manages the subscription. AerFrame will use this only for Push Notification Service and ignores this for Long Polling.

criteria

Mandatory

Must specify ServiceProfile names as "SP:sp1,sp2,sp3" or "SP:*" to subscribe for all service profiles under the account.

clientCorrelator

Optional

A correlator that the client can use to tag the subscription. Clients can use this to identify subscriptions and avoid duplicate subscriptions. AerFrame stores it as it is without modifying.

resourceURL

Optional

Generated by the AerFrame service and included in the response. The URL identifies the newly created resource.

link

Optional

Not used by AerFrame.

Table 9: AerFrame Inbound SMS Message Subscription

Name

Type

Presence

Description

notifyURL

URI

Mandatory

Notify Callback URL.

callbackData

String

Optional

This is passed back in each notification to the client application. Applications use it for correlation purposes.

notificationFormat

ENUM (XML, JSON)

Optional

AerFrame supports only JSON.

Table 10: AerFrame Subscription CallbackReference

SMS Request Operations

Operation

Request URI

Description

POST

/smsmessaging/v2/{accountId}/outbound/{applicationShortName}/requests

Send Outbound (MT) SMS

GET

/notificationchannel/v2/{accountId}/longpoll/{channelId}

Get Inbound SMS and Outbound SMS Delivery Info Notifications

POST

/smsmessaging/v2/{account}/acknowledgement

Acknowledge Inbound SMS

Table 11: AerFrame SMS Request API Operations

Name

Presence

Description

address

Mandatory

Array of destination addresses to send SMS to. This version of AerFrame accepts IMSI.

senderAddress

Mandatory

Sender address represent the application to which return message or delivery info may be sent. It should match the applicationShortName in the URL.

senderName

Optional

Not used by AerFrame.

charging

Optional

Not used by AerFrame.

receiptRequest

Optional

Not used by AerFrame. AerFrame uses subscription to deliver the delivery info. If a subscription exists for the serviceProfile then all delivery info will be delivered to the notification channel associated with subscription.

outboundSMSTextMessage

Choice

Should be used when sending text messages. AerFrame uses 7-bit encoding when delivering text messages to device. One of outboundSMSTextMessage or outboundSMSBinaryMessage must be present.

outboundSMSBinaryMessage

Choice

Should be used when sending binary messages. AerFrame uses 7-bit/8-bit encoding when delivering binary messages to device. One of outboundSMSTextMessage or outboundSMSBinaryMessage must be present.

clientCorrelator

Optional

Not used by AerFrame.

ttlInSeconds Optional Sets the relative validity period for this message request. This is the number of seconds this outboundSMS will remain valid and periodic retries will be done. Valid values are between 0 and 259200 seconds (72 hours). A value of zero will use the carrier's default validity period for MT-SM for carrier delivered MT-SM. If this parameter is omitted, then the AerFrame defaults are used (30 seconds for carrier delivered MT-SM, 72 hours for Global SIM store and forward service).

Note that this parameter is only honored if the destination device is set for carrier-delivered MT-SM or a Global SIM device whose service code is configured for the store and forward service; otherwise, this parameter is ignored.

Setting a large value of ttlInSeconds for a device that is offline will result in the final status (Delivered to Terminal or failed) notification not available until the ttlInSeconds period has elapsed.

resourceURL

Mandatory

Generated by AerFrame and included in the response.

link

Optional

Not used by AerFrame.

deliveryInfoList

Optional

Not used by AerFrame.

Table 12: AerFrame Outbound SMS Request Attributes

Name

Presence

Description

message

Mandatory

Short text message content. AerFrame does not accept empty messages.

The message text can have characters in ASCII, some from ISO-8859-1, and Unicode characters. However, the characters supported in the GSM7 basic and extended characters (as defined in the 3GPP TS 23.038 standard) set gets delivered to the device.

The characters that are not translatable into GSM7 are replaced by a space character.

The maximum length of the message field content is 160 characters.

NOTES:

The GSM7 character set uses different values for some of the ASCII characters and translates the input ASCII characters to their GSM7 equivalent characters.

Some GSM7 Extension characters are represented as two characters. While converting these extension characters, an <ESCAPE> character (value of 0x1b) is inserted before the actual GSM7 Extension character.Therefore, for each extension characters used in the message text, the maximum length of the message gets be reduced by one (since the <ESCAPE> character uses a character position). These Extension characters are:

  • ^ : Caret or circumflex
  • { }: Left and right curly brackets
  • \ : Backslash
  • [ ]: Left and right square brackets
  • ~ : Tilde sign
  • | : Vertical bar
  • € : The Euro currency symbol

Table 13: AerFrame OutboundSMSTextMessage

Name

Presence

Description

message

Mandatory

Short binary message content. Base64 Encoded. AerFrame does not accept empty messages.

encodingScheme

Mandatory

"7-Bit" or "8-Bit" or "16-Bit".

However, the values AerFrame accepts as encoding schemes don't map exactly to the values the mobile terminal receives:

AerFrame Value (SMPP) Value Received Meaning
7-Bit 1 IA5 (CCITT T.50)/ASCII (ANSIX3.4)
8-Bit 4 Octet unspecified (8-bit binary)
16-Bit 8 UCS2 (ISO/IEC-10646)

Therefore, if you send the 16-Bit binary data to your devices (not having the Aeris Global SIM), the devices will see or receive the data coding as UCS-2.

Table 14: OutboundSMSBinaryMessage

Name

Presence

Description

callbackData

Optional

Callback Data set in the inbound subscription is returned without modification.

inboundSMSMessage

Mandatory

Inbound SMS Message received from device.

Table 15: AerFrame InboundSMSMessageNotification

Name

Presence

Description

destinationAddress

Mandatory

Destination Address of the message from the device.

senderAddress

Mandatory

IMSI of device sending SMS.

serviceProfile

Mandatory

Service Profile of the device for which the message was received.

message

Mandatory

SMS message as binary base 64 encoded message. AerFrame does not accept empty messages.

The interpretation of the message after decoding from base64 depends on the value of the encodingScheme:

  • If the encodingScheme is "7-Bit", then the decoded message will be in ASCII / ISO-8859-1 format. Each 7-Bit character will occupy an 8-bit octet in the decoded message. Note that the original message from the device was likely encoded as GSM7, possibly with GSM7-extension characters (two character sequences that represent a single extension character). The GSM7 encoding uses different numeric values for several characters than is used in ISO-8859-1. Those characters will be converted to ISO-8859-1.
  • If the encodingScheme is "8-bit", the decoded message will be identical, byte for byte, to the message that was sent from the device. There is no conversion.
  • If the encodingScheme is "16-bit", then the decoded message will likely be in UCS2 encoding, where each character is represented by 16-bits.

NOTE:

The use of the Euro-Currency-sign ("€") should be avoided in 7-Bit MO-SM. There is no ISO-8859-1 character value for the Euro-Currency-sign. (The ISO-8859-1 standard was created before the Euro currency was created).

  • If your device is an Aeris Global SIM and it sends, via a 7-Bit MO-SM, a Euro-currency-sign, then the Euro-currency-sign will be converted to its Unicode equivalent (16-bits 0x20ac).
  • If your device is an Aeris Dual-Mode A-LH and it sends, via a 7-Bit MO-SM, a Euro-currency-sign, then the AT&T network will convert the rest of the message to ISO-8859-1 (as it normally does), except for the Euro-currency-sign character, which will remain as a GSM7-extension character (16 bits 0x1b65).
encodingScheme Mandatory "7-Bit" or "8-Bit" or "16-Bit".
dateTime Mandatory Time the message was received from device.
resourceURL Optional Placeholder to reference SMS message. Not used by AerFrame.

link

Optional

Placeholder to reference related resources. Not used by AerFrame.

messageId

Mandatory

AerFrame generated and assigned unique message id.

Table 16: AerFrame InboundSMSMessage

Name

Presence

Description

callbackData

Mandatory

Callback Data set in the outbound SMS delivery info subscription is returned without modification,

deliveryInfo

Mandatory

Outbound SMS delivery info.

link

Optional

Placeholder to reference related resources. Not used by AerFrame.

Table 17: AerFrame DeliveryInfoNotification

Name

Presence

Description

address

Mandatory

Device identifier referred in OutboundSMSMessage. AerFrame uses IMSI.

deliveryStatus

Mandatory

Defines the SMS delivery status, which can be one of following:

Status Type Description
DeliveredToNetwork Interim

Message is successfully sent to a carrier partner for delivery to the destination device.

This is an interim status and indicates that the message delivery is "in progress" and the final status will be delivered later.

DeliveredToTerminal Final Message is successfully delivered to the destination device.
DeliveryImpossible Final Message delivery failed. The most likely cause is that the destination device is offline or unable to respond during the time-to-live of the message.
DeliveryNotificationNotSupported Final Not used.
DeliveryUncertain Final Not possible to determine if the message delivery was successful or failed. This would be an extraordinary unusual condition. No further information will be provided for this particular message.
MessageWaiting Final Not used.

NOTE:

A final status means that this is the final DeliveryInfo status for this particular message. An interim status indicates that additional DeliveryInfo status will be provided for this particular message later.

description

Optional

More details about the status.

link

Mandatory

Reference (Resource URL) to the send SMS request resource to which this deliveryInfo corresponds.

Table 18: AerFrame DeliveryInfo

Name

Presence

Description

message

Mandatory

Array of AcknowledgeMessage.

Table 19: AerFrame AcknowledgeMessageRequest

Name

Presence

Description

message

Mandatory

Array of AcknowledgeMessage.

Table 20: AerFrame AcknowledgeMessageResponse

Name

Presence

Description

messageId

Mandatory

Message Id of the message to be acknowledged.

messageType

Mandatory

Inbound or Outbound.

serviceProfile

Mandatory

Service Profile of the device for which the message was received.

success

Mandatory

true or false. Receipt Status of the message. Specifies whether the message was received/processed successfully by the application.

acknowledged

Mandatory

Populated by AerFrame denoting the status of the acknowledgement of the message.

Table 21: AerFrame AcknowledgeMessage

See also Send/Receive SMS with AerFrame API.

Network Service API Operations

AerFrame Network Service API is a set of APIs to access core network features like Clear Registration, Get Local Dialable Number, and Get Network Location. The API for getting a local dialable number allows you to deploy devices securely with non-dialable numbers but still reach them when needed. The API for resetting network registration can be a powerful tool for resolving device connectivity issues.

Operation

URI

Description

DELETE

/networkservices/v2/{accountId}/devices/ {deviceIdType}/{deviceId}/registration

Clear Registration for a Device: Clears registration of device from the serving VLR and SGSN. DeviceIdType could be IMSI or MSISDN. DeviceId is the corresponding IMSI or MSISDN. The Cancel Location is sent on a "best effort" basis. If the device's location is not known, then a cancel location cannot be sent and the request is silently ignored. There is no result for a cancel location request.

GET

/networkservices/v2/{accountId}/devices/ {deviceIdType}/{deviceId}/localDialableNumber

Get Local Dialable Number: Obtain a temporary local dialable number for the device. DeviceIdType could be IMSI or MSISDN. DeviceId is the corresponding IMSI or MSISDN.

GET /networkservices/v2/{accountId}/devices/ {deviceIdType}/{deviceId}/ networkLocation?apiKey=<apiKey> Get Network Location of the Device: This API call fetches the network-based location of a GSM, Fusion North America, or Fusion Global device. This API fetches information about the base station or the cell tower ID to determine the device location where the device was recently connected or registered. This API accepts the IMSI or MSISDN as DeviceIdType to identify the device. DeviceId is the corresponding IMSI or MSISDN. This API accepts the unique API key that is assigned to the customer account for authentication and authorization of the API call. This API key can be retrieved from the AerPort Portal.

This API returns the real-time information about the device network location.

  • If the network is able to page the device successfully (device is on and registered in the network), then you will receive the location response with the current location information.
  • If the network is unable to page the device (device is off), then you might get a location response with the last recorded location values from the network if the location was recorded within the last approximately 36 hours. Otherwise, the API returns the information with all core elements of the location response as zeros or with an error "Location not found."

NOTE:

  • We recommend that you not exceed 1 request every 30 minutes per device.
  • Making more frequent location requests per device could result in timeouts.

Table 22: AerFrame Network Service API Operations

Name

Presence

Description

dialableNumber

Mandatory

Local dialable number that can be used to make MT Voice call.

numberNOA

Mandatory

Nature of address of the returned dialable number.

numberNP

Mandatory

Numbering plan of the returned dialable number.

requestCompletedTimestamp

Mandatory

Timestamp in milliseconds when the request was completed by the network.

validForSeconds

Mandatory

Approximate time in seconds for which the dialable number is valid.

requestId

Mandatory

Reference to the request Id. Used internally by AerFrame. Can be used as reference in support tickets.

Table 23: AerFrame Network Service API LocalDialableNumberResponse

Name

Presence

Description

responseType

Mandatory

Always returns as 'Cell ID' because this API is intended to retrieve the cell ID only.

mcc

Mandatory

Defines the Mobile Country Code (MCC) to identify the country of the device location. For example, 404 and 405 represent India, 310, 311, 312, 313, 314 and 316 represent USA, and so on.

mnc

Mandatory

Defines the Mobile Network Code (MNC) to identify the mobile operator in the MCC. See Cell Tower Locations below for additional details.

See the Mobile Country Code list on Wikipedia for a quick reference.

lac

Mandatory

Defines the Location Area Code (LAC) which is the unique identifier of the current location area. This LAC is a group of base stations that are used together to optimize signalling.

cellId

Mandatory

Defines the unique identifier of the Base Transceiver Station (BTS) or sector of a BTS within a LAC.

The Cell ID can be zero because it does not depend on the data returned from the last known switch. If the device is registered with switch A and then turned off and moved to another location or country and has not yet registered, then switch A is still the last known switch but the API returns no location because the device is no longer registered at that switch.

To keep getting updated Cell ID, it is recommend that you execute the API on regular intervals to have updated information of the Cell ID.

NOTE: If the Cell ID is zero for any reason, use the value of mcc, mnc, and lac fields to estimate the location (country and state) of the device.

locationTimestamp

Optional

If not NULL or non-zero, then this is the timestamp when the location was received.This is non-NULL and non-zero if there is a location for this device.

ageOfLocation Optional

Defines the age of location information in Minutes corresponding to how long ago the location information was retrieved from the network. Returns NULL or Zero if no location information is available.

state Optional

Returns the CS state, which can be one of the following:

  • 0 = assumedIdle
  • 1 = camelBusy
  • 2 = netDetNotReachable
  • 3 = notProvidedFromVLR
requestId Mandatory

Reference to the request Id. Used internally by AerFrame. Clients can use it as reference in support tickets.

destinationType Mandatory

Returns the switch type CS (Circuit Switch) or PS (Packet Switch) to represent the location result. Since this API works only on CS (Circuit Switch), this field always return CS as its value.

destinationTypeCode Mandatory

Returns 7 always to represent the destination type value, where 7 represents VLR (circuit switched PSI).

Table 24: AerFrame Network Service API LocationResponse

Cell Tower Locations

Cell tower locations are composed of these elements:

  • mcc: mobile country code
  • mnc: mobile network code
  • lac: location area code
  • cellId: the unique identifier of the Base Transceiver Station (BTS) or sector of a BTS within a LAC

Running Get Network Location provides you with values for these elements. You can use these four values to look up the latitude and longitude coordinates of the tower using a tool such as Google Gelocation API or Mozilla Location Service data file. This information tells you the current geographic location of the device.

In the table below, note that mcc, mnc, lac, and cellId return integer values. In some cases, the returned value of mnc or cellId might be a one- or two-digit value like 6 or 10 that is missing one or two leading zeros. For example, the location returned could be mcc=310 and mnc=3. In this case, you would need to add leading zeros to the mnc to end up with 3 digits (310 003) when looking up the latitude and longitude coordinates.

Here are the rules for the workaround:

  • Add 1 leading zero to a single-digit mnc.
  • Add 1 leading zero to a two-digit mnc in the following cases:
    310 010 311 030 334 060 404 045
    310 011 311 040 334 070 405 034
    310 012 311 050 334 080 708 030
    310 013 311 070 334 090 708 040
    310 016 311 080 338 020 714 020
    310 020 311 090 338 050 722 010
    310 030 312 010 342 050 722 020
    310 032 312 040 344 030 722 070
    310 033 312 090 346 050 732 020
    310 040 316 010 352 030  
    310 050 316 011 352 050  
    310 070 334 010 360 050  
    310 080 334 020 365 010  
    310 090 334 030 366 020  
    311 010 334 040 366 050  
    311 020 334 050 ** 376 050  

** There is one ambiguous case where adding a leading zero might not be correct. 334 050 is not the same as 334 50. Both are valid. If the device is in this region of Mexico, please be aware that this scenario is possible.

  • Add 2 leading zeros to a one-digit mnc in the following cases:
    310 003 346 006 708 002 750 001
    310 004 350 000 732 001  
    311 000 708 001 732 002  

Example Requests and Responses

Clear Registration for a Device

URL DELETE https://api.aerframe.aeris.com/networkservices/v2/{accountId}/devices/imsi/204111211111259/registration?apiKey={{accountApiKey OR appApiKey}}

Get Local Dialable Number

URL GET https://api.aerframe.aeris.com/networkservices/v2/{accountId}/devices/imsi/204043396000768/localDialableNumber?apiKey={{accountApiKey OR appApiKey}}

Response:

{ 
   "numberNoa": 16 
   "numberNp": 1
   "reqCompletedTimestamp": 1394239535000 
   "validForSeconds": 30
   "requestId": "00009c71-30b8-954d-00b3-ff39179e8d5a" 
   "dialableNumber": "19254350381" 
}

Get Network Location of the Device

URL GET https://api.aerframe.aeris.com/networkservices/v2/{accountId}/devices/imsi/204043396622367/networkLocation?apiKey={{accountApiKey OR appApiKey}}

Response:

{ 
   "responseType": "Cell ID", 
   "mcc": 404, 
   "mnc": 11, 
   "lac": 1013, 
   "cellId": 0, 
   "locationTimestamp": 1533581751.01775, 
   "ageOfLocation": 0, 
   "state": 0, 
   "requestId": "000ba911-dabf-b375-0a43-e1c55e5e4da7", 
   "destinationType": "CS",
   "destinationTypeCode": 7 
}

LTE-M Shoulder Tap Operations

This set of operations applies only to Fusion North America devices.

A challenge in communicating with battery-constrained devices that utilize power saving functions is to contact the device to trigger some action. This process is called a shoulder tap. In 2G/3G devices, a shoulder tap is typically done using SMS, which has a built-in service to store and forward the message. However, SMS is not always available in LTE and NB-IoT devices, which mostly support IP-based data connectivity only. The mobile nature of cellular devices, such as those that roam across serving gateway boundaries and different mobile network operators while the device is in a power-saving state, makes it difficult to deliver shoulder tap packets to the device in a reliable and cost-efficient manner. Additionally, the extended buffering of data at the serving gateway is not always guaranteed and is prone to resource constraints at the serving gateway.

The LTE-M Shoulder Tap APIs send a beacon of shoulder tap packets with a unique identifier to the device at a specified interval. The frequency of the shoulder tap beacon message is dynamically calculated to factor in the device’s listen window size between sleeps and wake-up duration time.

Notes:

  • Access will be only via HTTPS.
  • The version path segment should appear immediately after the endpoint.
  • The base path for the following resources is
    • https://{{hostname}}/shouldertap/v2/{{accountId}}
    • where {{hostname}} is the AerFrame hostname (e.g., api.aerframe.aeris.com), and {{accountId}} is the account ID of the account of the customer making the request.
  • Authentication is the same as for all existing AerFrame services. It is done using the standard customer account AerFrame API Key (placed in the header of the REST request) as is done for all other AerFrame operations.
  • Shoulder taps sent using a customer’s API Key can only be sent to devices owned by that customer account.
  • Shoulder taps can be sent individually or in a batch of up to 1000 devices.
  • Payloads can be up to 140 bytes.

When a shoulder tap is sent to a device:

  • To successfully receive a message, the device must be on, in awake mode, with receiver/listening software running.
  • If the device is not listening, it will not receive messages.
  • When the device comes online, the message arrives.
  • The shoulder tap will not wake up the device. Rather, the shoulder tap will be repeated or scheduled for a time when the device will be listening.

Operation

Request URI

Description

POST

/s-tap

This API sends a batch of one or more shoulder tap messages. (This is the same interface to send one or many shoulder taps; the same IMSI device can appear multiple times in the array of messages in a batch.)

If the same device is in the batch multiple times, each shoulder tap for that device is processed independently from the others.

The parameter names starting with “batch” apply to the entire batch. If an individual shoulder tap does not specify a value for the corresponding parameter, the batch value will be used. The request will be rejected if a batch parameter is not specified and an individual required shoulder tap parameter is not specified.

DELETE /s-tap/{{type}}/{{reqId}}

This API cancels a shoulder tap request.

The type is one of:

  • request: This cancels an shoulder tap with the specified reqId.
  • imsi: This cancels all shoulder taps for the device with the IMSI given as the reqId parameter.

If there is an error (not HTTP status 200), no response body is returned.

For an individual shoulder tap cancellation (by request ID), the returned reqIdList has only a single element in a successful cancellation. There is no response body for HTTP status values >= 400.

For cancellation by device ID, if there were no pending shoulder taps for that device, the HTTP status will be 404.

Table 25: Shoulder Tap API Operations

Individual or Batch Operations

You can choose either a batch payload or an individual payload.

If you choose to send a payload to an individual device:

  • Omit batchPayloadType, batchPayload, and batchExpires or set them to null.
  • Specify message, idType, id, payloadType, payload, and expires.
  • Optionally specify deliveryMechanism, deliveryPort, powerMode, powerSleepInterval, and powerAwakeInterval.

If you choose a send a payload to a batch of devices:

  • Specify batchPayloadType, batchPayload, and batchExpires.
  • Specify message, idType, and id.
  • Omit payloadType, payload, and expires or set them to null.
  • Optionally specify deliveryMechanism, deliveryPort, powerMode, powerSleepInterval, and powerAwakeInterval.

Timing a Shoulder Tap Operation

Once the request is submitted, the beacon is continually sent until the expiration. More specifically, the API sends a beacon of shoulder tap packets with a unique identifier to the device(s) at a specified interval until the shoulder tap expires or until the shoulder tap is cancelled.

When the request is submitted, the device(s) can be either asleep or awake. Because we do not know the start of the awake cycle of the device, we begin attempting to deliver the message immediately.

How often we attempt to deliver the payload is calculated from the powerAwakeInterval. powerAwakeInterval specifies the number of seconds that the device stays awake whenever it wakes up. We calculate half of the powerAwakeInterval as X and send the payload every X seconds from the time the request is submitted until the specified expiration time.

Note: powersleepinterval and powermode will be implemented in a future release.

The Contents of a Shoulder Tap Packet

A shoulder tap packet includes several pieces of information.

Field

Size of Field

Description

Sample Value (hex) Interpretation of Sample Value
STX One byte A literal STX character 0x02  
Message Type Two bytes Denotes what protocol the remainder of the packet will follow in hex-ascii format. Always 0x3031 for UDP0. 0x3031 '01' (in ASCII) denotes UDP0
Sequence Number Four bytes Denotes the sequence number of the shoulder-tap in hex-ascii format. 0x42323645 'b26e' (in ASCII) denotes sequence number 45,678 (in decimal)
Payload Length Two bytes Denotes, in hex-ascii format, how many bytes the payload will be. 0x3038 '08' (in ASCII) denotes a payload of eight bytes
Payload Variable length Binary data. 0x48692c204d6f6d21 'Hi, Mom!' if interpreted as ASCII or UTF-8
ETX One byte A literal ETX character 0x03  

Table 26: Packet Contents

For the UDP0 protocol, the device receiving a shoulder-tap must construct the request ID by appending the device's IMSI, a dash, and the decimal representation of the sequence number of the shoulder-tap.

For example, if the device's IMSI is 123456789012345 and the (hex) value of the shoulder-tap's sequence number is 0x42323645, then the request ID is "123456789012345-45678". To convert the hex value 0x42323645, we first convert it to ASCII characters (B26E), and then convert those ASCII characters to decimal using base 16.

This request ID must be used to cancel the shoulder-tap via the DELETE API; otherwise, the Aeris AerFrame API will continue to deliver the shoulder-tap.

Name

Presence

Description

batchPayloadType Optional The parameter batchPayloadType must be either “ASCII” or “BASE64”. It is validated only if an individual message does not specify a payloadType and thus uses the batchPayloadType. batchPayloadType can be specified with or without batchPayload.
batchPayload Optional This parameter specifies the payload for the batch. batchPayload can be specified with or without batchPayloadType. If batchPayloadType is not specified, each individual message in the batch must specify the payloadType. The contents of batchPayload are validated (for example, a valid base64 value if the payloadType is BASE64) only if an individual message does not specify a payload and thus uses the batchPayload. The maximum batchPayload length is 140 bytes.
batchExpires Optional This parameter specifies the expiration for the batch in seconds. It will be used as the expires value for a message if the message does not specify an expires parameter.

If the parameter is omitted, then a default of 72 hours is used. 72 hours is 259,200 seconds.

message Mandatory The message parameter is an array of individual shoulder taps. If the message parameter is null or empty, the system rejects the entire batch.
idType Mandatory The only support idType is "IMSI". If the idType parameter is not “IMSI”, the individual shoulder tap is rejected.
id Mandatory The IMSI ID.
payloadType Optional

payloadType is either “ASCII” or “BASE64”. It defines how the payload parameter is to be interpreted.

If ASCII, then only printable ASCII characters (including space, CR, and LF) are in the payload.

If BASE64, then the payload must be in BASE64 format (RFC4648).

In either case, the payload is delivered in binary form in the UDP0 delivery mechanism. (BASE64 payloads are converted to binary, and ASCII payloads are passed through without conversion.)

If payloadType is neither “ASCII” nor “BASE64”, the individual shoulder tap is rejected.

If the payloadType is not present, then the batchPayloadType will be used.

If both the payloadType and the batchPayloadType are not present and a payload is present, then the message will be rejected.

If the payload is omitted or is an empty string, then the payloadType and batchPayloadType are not required.

payload Optional

The payload parameter represents the payload for a particular shoulder tap. The maximum payload length is 140 bytes.

If the payload is not present, then the batchPayload will be used.

If the payload is not present (or is an empty string) and the batchPayload is not present (or is an empty string), then the shoulder tap will contain a zero length payload.

expires Optional

Set the value of expires to 0 to make one attempt at a shoulder tap.

If it is greater than zero, it represents the time in seconds from request submission to when it expires.

If expires is less than zero, the individual shoulder tap is rejected.

If the parameter is omitted, then a default of 72 hours is used. 72 hours is 259,200 seconds.

If expires is greater than the maximum value (72 hours or 259,200 seconds), the shoulder tap message is rejected.

deliveryMechanism Optional

The only supported delivery mechanism is “UDP0”.

If the parameter is omitted, then “UDP0” is used as the default.

If deliveryMechanism is not “UDP0”, the individual shoulder tap is rejected.

deliveryPort Optional

If the optional deliveryPort parameter is omitted, then a value of 23747 is used as the default.

If the deliveryPort parameter is present, it must be greater than or equal to 1025 and less than or equal to 65535.

If deliveryPort is outside of that range, the individual shoulder tap is rejected.

powerMode Unused This parameter is used to help with scheduling the shoulder tap. Must be either “PSM” or “eDRX”. Any other value causes the system to reject the individual shoulder tap.
powerSleepInterval Unused

This parameter is used to help with scheduling the shoulder tap. The powerSleepInterval is the time in seconds that the device is asleep (not reachable). Its value depends on the powerMode:

  • PSM: the difference in values (in seconds) of 3GPP timers T3412 - T3324 (the TAU Period less the Active Timer).
  • eDRX: The eDRX cycle (TeDrx) converted and rounded to seconds.

If powerSleepInterval is specified, it must be greater than or equal to zero.

If it is less than zero, the individual shoulder tap is rejected.

powerAwakeInterval Optional This parameter is used to help with scheduling the shoulder tap. The time in seconds that the device is awake: 3GPP Timer T3324 (the Active Timer, in seconds).

The mimimum value is 1.

If the powerAwakeInterval field is specified for a message, it must be greater than zero.

If it is less than or equal to zero, the individual shoulder tap is rejected.

Table 27: POST /s-tap Request Parameter Descriptions

Batch Parameters

Note that the batch parameters are not validated for the batch as a whole. They are provided as a default only for individual messages in the batch if the message does not provide the parameter. The validations for the parameter values taken from the batch parameters are validated when each message request is processed. An invalid value for a batch parameter will not cause the batch to be rejected, but will cause each individual message that uses that value to be rejected.

A maximum of 1000 devices can be included in a batch.

The maximum message payload length is 140 bytes.

Payload Validations

  • If both the payload and the batchPayload are not present, then the shoulder tap is considered to have a zero-length payload, which is allowed.
  • If the payloadType (or batchPayloadType if payloadType is not present) is BASE64, then the payload is validated to be in BASE64 format; if that validation fails, this message is rejected.
  • The maximum size of a payload is 140 bytes (140 ASCII characters, or 140-byte decoded binary payload if in BASE64); the message will be rejected if the payload is too large.
  • If the payloadType is ASCII and the payload contains non-ASCII printable (including: space, tab, CR, LF) characters, the message will be rejected. If you need non-printing ASCII characters, or other character sets such as Unicode, encode them as a BASE64 payload.

Name

Description

batchAcceptanceStatus batchAcceptanceStatus is the status of the overall batch. Returns one of: "ALL_ACCEPTED" or "SOME_ACCEPTED" or "ALL_REJECTED".
batchId The batchId is an opaque and unique identifier for the batch.
msgStat msgStat is an array of individual statuses for each of the messages in the request batch, in the same order as the requests, so that the user can match the status of each message requested.
idType The idType is the same as the request parameter.
id The id is the same as the request parameter.
reqId reqId is an opaque identifier assigned to this message request. This is the identifier that you must use to cancel the request.
deliveryMechanism The deliveryMechanism is the same as the request parameter.
timestamp timestamp is the epoch time that the request was processed. Epoch time refers to the Unix-standard Epoch Time of the number of seconds since 1970.0101 UTC.
attemptCount attemptCount will be zero since there have not yet been any attempts made.
lastAttemptTimestamp lastAttemptTimestamp will be zero since there have not yet been any attempts made.
msgStatus msgStatus is the acceptance status of the individual request. The value can be either “accepted” or “rejected”.
error If the message is rejected, the error field will contain an appropriate error message. If the message is accepted, the error field will be a zero-length string.
expires The expires field is the same as the request parameter.
expirationTime expirationTime is an epoch time for when the message will expire.

Table 28: POST /s-tap Response Parameter Descriptions

HTTP Status Code

Condition

200 Batch processed. Check the msgStat for the accepted/rejected status of individual messages.
400 Error in request; entire batch rejected.
504 Internal problem: an internal service did not respond before timeout.

Table 29: POST /s-tap Response HTTP Status Codes

Name

Description

reqIdList

The response has a list of the reqIds that were cancelled.

HTTP Status for any cancellation method:

  • 400: bad request type (it needs to be one of “request” or “imsi”)
HTTP Status for an individual request cancellation:
  • 200: OK. shoulder tap cancelled. There will be one reqId in the reqIdList in the response.
  • 404: reqId not found, aleady cancelled, or already expired. (no response body).
  • 504: Internal problem: STS service did not respond before timeout.

HTTP Status for a device ID shoulder tap cancellation:

  • 200: OK. shoulder tap(s) cancelled. There will be zero or more reqIds in the response.
  • 404: Device not found, or no shoulder taps were cancelled (no response body).
  • 504: Internal problem: STS service did not respond before timeout.

Table 30: DELETE /s-tap/{{type}}/{{reqId}} Response Parameter Descriptions

Sample Layout of the POST Request

{
  "batchPayloadType": "ASCII" or "BASE64",
  "batchPayload": "xxxx",
  "batchExpires": sss,
  "message": [
    {
      "idType": "IMSI",
      "id": "nnnn",
      "payloadType": "ASCII" or "BASE64",
      "payload": "xxxx",
      "expires": sss,
      "deliveryMechanism": "UDP0",
      "deliveryPort": 23747,
      "powerMode": "PSM" or "eDRX",
      "powerSleepInterval": sss,
      "powerAwakeInterval": sss
    }
  ]
}

Example of an Individual Request

{
  "message": [
    {
      "idType": "IMSI",
      "id": {{s-tap-imsi}},
      "payloadType": "ASCII",
      "payload": "My Payload",
      "expires": 0,
      "deliveryMechanism": "UDP0",
      "deliveryPort": 23747,
      "powerMode": "PSM",
      "powerSleepInterval": 120,
      "powerAwakeInterval": 60
    }
  ]
}

Example of a Batch Request that Sends the Same Message to All Devices

{
  "batchPayloadType": "ASCII",
  "batchPayload": "Hello World",
  "batchExpires": 0,
  "message": [
    {
      "idType": "IMSI",
      "id": {{s-tap-imsi1}},
      "deliveryMechanism": "UDP0",
      "deliveryPort": 23747,
      "powerMode": "PSM",
      "powerSleepInterval": 120,
      "powerAwakeInterval": 30
    },{
      "idType": "IMSI",
      "id": {{s-tap-imsi2}},
      "deliveryMechanism": "UDP0",
      "deliveryPort": 23747,
      "powerMode": "PSM",
      "powerSleepInterval": 120,
      "powerAwakeInterval": 60
    },{
      "idType": "IMSI",
      "id": {{s-tap-imsi3}},
      "deliveryMechanism": "UDP0",
      "deliveryPort": 23747,
      "powerMode": "PSM",
      "powerSleepInterval": 120,
      "powerAwakeInterval": 60
    }
  ]
}

Example of a Batch Request that Sends the Same Message to All Devices Except Those that have Specified an Individual Payload

{
  "batchPayloadType": "ASCII",
  "batchPayload": "Hello World",
  "batchExpires": 0,
  "message": [
    {
      "idType": "IMSI",
      "id": {{s-tap-imsi4}},
      "deliveryMechanism": "UDP0",
      "deliveryPort": 23747,
      "powerMode": "PSM",
      "powerSleepInterval": 120,
      "powerAwakeInterval": 30
    },{
      "idType": "IMSI",
      "id": {{s-tap-imsi5}},
      "payloadType": "BASE64",
      "payload": "Uy1UQVAgTUVTU0FHRSY/",
      "expires": 600,
      "deliveryMechanism": "UDP0",
      "deliveryPort": 23747,
      "powerMode": "PSM",
      "powerSleepInterval": 120,
      "powerAwakeInterval": 60
    },{
      "idType": "IMSI",
      "id": {{s-tap-imsi6}},
      "deliveryMechanism": "UDP0",
      "deliveryPort": 23747,
      "powerMode": "PSM",
      "powerSleepInterval": 120,
      "powerAwakeInterval": 60
    }
  ]
}

Sample Layout of the POST Response

{
  {
    "batchAcceptanceStatus": "ALL_ACCEPTED" or "SOME_ACCEPTED" or "ALL_REJECTED",
    "batchId": "xxx",
    "msgStat": [
    {
      "idType": "xxx",
      "id": "xxx",
      "reqId": "xxx",
      "deliveryMechanism": "xxx",
      "timestamp": 123,
      "attemptCount": 0,
      "lastAttemptTimestamp": 0,
      "msgStatus": "accepted" or "rejected",
      "error": "error text",
      "expires": 123,
      "expirationTime": 123
    }
  ]
}

Sample Layout of the DELETE Response

{
  "reqIdList": [
    "xxx"
  ]
}

For additional help, Aeris is providing a sample reference implementation in github.

https://github.com/aeristhings/aeris-modsdk-py

Additional information on the Udp0 shoulder-tap protocol is available here:

https://github.com/aeristhings/aeris-modsdk-py/wiki/Udp0-Shoulder-Tap

Service / Policy Exception Codes and Messages

  • AerFrame 2.1 APIs use standard HTTP Status Codes to convey success or failure response
  • API response content, if any, is of type application/json

This table describes the Request Errors schema:

Name

Presence

Description

Link

Optional

List of resources that are related to the error. Not used by AerFrame.

serviceException

Optional

Captures AerFrame service and request validation exception (e.g. Device not found). Either serviceException or policyException will be present.

policyException

Optional

Captures AerFrame policy/business rule violations. Either serviceException or policyException will be present.

Table 31: AerFrame Request Errors

This table describes the Service / Policy Exceptions schema:

Name

Presence

Description

messageId

Mandatory

Error code (See section Service and Policy Exception Code for full list).

text

Mandatory

Error text with variable placeholders.

variables

Optional

List of values matching the number of placeholders in text.

Table 32: AerFrame Service and Policy Exceptions

Sending a message to an invalid device id returns this response:

aerframe_invalid_device_response

Service Exceptions

SVC0001 = A service error occurred. Error code is {0}.

SVC0002 = Invalid input value for message part {0}.

SVC0003 = Invalid input value for message part {0}, valid values are {1}.

SVC0004 = No valid addresses provided in message part {0}.

SVC0005 = Correlator {0} specified in message part {1} is a duplicate.

SVC0006 = Group {0} in message part {1} is not a valid group.

SVC0007 = Invalid charging information.

SVC0008 = Overlapped Criteria {0}.

SVC0280 = Message too long. Maximum length is {0} characters.

SVC0281 = Data format not recognized for message part {0}.

SVC0283 = Delivery Receipt Notification not supported.

SVC0400 = Failed to submit Clear Registration for {0}.

SVC0401 = Service Error: Failure code {0}, Failure Message {1}.

SVC0402 = Service timed out. Please try again.

SVC1000 = No resources.

SVC2000 = The following service error occurred: {0}. Error code is {1}.

Policy Exceptions

POL0001 = A policy error occurred. Error code is {0}.

POL0002 = Privacy verification failed for address {0}, request is refused.

POL0003 = Too many addresses specified in message part {0}.

POL0004 = Unlimited notification request not supported.

POL0005 = Too many notifications requested.

POL0006 = Group specified in message part {0} not allowed.

POL0007 = Nested group specified in message part {0} not allowed.

POL0008 = Charging is not supported.

POL0009 = Invalid frequency requested.

POL0010 = Requested information unavailable as the retention time interval has expired.

POL0011 = Media type not supported.

POL0012 = Too many description entries specified in message part {0}.

POL0013 = Duplicated addresses.

POL1009 = User has not been provisioned for {0}.

POL1010 = User has been suspended from {0}.

POL1016 = File size exceeds the limit {0}.

POL1019 = Binary SMS is not allowed.

POL1020 = MaxBatchSize exceeded. The maximum allowed maxBatchSize is {0}.

POL2000 = The following policy error occurred: {0}. Error code is {1}.

AerFrame Error Codes

Value

Error

-1

Gsmmap pack failed

-2

Gsmmap validation failed

-3

Gsmmap submit failed

-4

Gsmmap timeout

-5

Gsmmap abort

-6

Gsmmap reject

-7

Gsmmap No Appropriate Stack Connection Available

-8

Device is unreachable

-9

Device location is unknown

-10

RTTL expired

Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.