API Overview

The AerFrame 2.1 API includes the following set of APIs:

  • SMS Messaging API

Derived from OMA Restful Short Messaging API. The outbound SMS (mobile-terminated, or “MT”) delivery info and inbound SMS (mobile-originated, or “MO”) 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.

  • Network Service API

Provides access to operations like Clear Registration and Get Local Dialable Number.

The following diagram describes the API structure.

API-Structure_4

Code Samples

Step 1 – Create SMS Application

Request

#the urllib package must be downloaded before the package can be imported
import json, urllib.request

#fill in all fields of data
data = {
'applicationName':'Test Application1',
'applicationShortName':'testApp1',
'applicationTag':'test1',
'description':'A sample AerFrame application'
}

#enter the account API key below
accountApiKey = "11111111-1111-1111-1111-111111111111"
#enter the account ID below
accountId = "1234"

url = "https://api.aerframe.aeris.com/registration/v2/" + accountId + "/applications?apiKey=" + accountApiKey

header = {'Content-Type':'application/json'}

req = urllib.request.Request(url, json.dumps(data).encode('utf-8'),header)
response = urllib.request.urlopen(req)

#response will return the unique application apiKey
print(response.read())

Response

{"applicationName":"Test Application1","applicationShortName":"testApp1","applicationTag":"test1","description":"A sample AerFrame application","apiKey":"22222222-2222-2222-2222-222222222222","resourceURL":"https:\/\/api.aerframe.aeris.com\/registration\/v2\/1234\/applications\/00000413-9d3d-be61-6232-99c5d661e0d9"}
Step 2 - Create Notification Channel

Request

import json, urllib.request

data = {
"applicationTag":"test", #enter in the applicationTag field
"channelData":{
"maxNotifications":"15",
"type":"nc:LongPollingData"
},
"channelLifetime":"7200",
"channelType":"LongPolling",
"clientCorrelator":"1234"
}

#enter the application API key returned in the create application step below
applicationApiKey = '22222222-2222-2222-2222-222222222222'
#enter the account ID below
accountId = '1234'

url = "https://api.aerframe.aeris.com/notificationchannel/v2/" + accountId + "/channels?apiKey=" + applicationApiKey
header = {'Content-Type':'application/json'}

req = urllib.request.Request(url, json.dumps(data).encode('utf-8'), header)
response = urllib.request.urlopen(req)

#use the callbackURL from this step as the notifyURL for Step 3
print(response.read())

Response

{"clientCorrelator":"4321","applicationTag":"test","channelType":"LongPolling","channelData":{"channelURL":"https:\/\/longpoll.aerframe.aeris.com\/notificationchannel\/v2\/1234\/longpoll\/00000f98-83fa-2f2a-3952-04114b6bbbb1","maxNotifications":15},"channelLifetime":7200,"callbackURL":"https:\/\/api.aerframe.aeris.com\/notificationchannel\/v2\/1234\/channels\/00000f98-83fa-2f2a-3952-04114b6bbbb1\/callback","resourceURL":"https:\/\/api.aerframe.aeris.com\/notificationchannel\/v2\/1234\/channels\/00000f98-83fa-2f2a-3952-04114b6bbbb1"}
Step 3 - Create Outbound (MT) SMS Delivery Info Subscription

Request

import json, urllib.request


data = {
  "callbackReference": {
    "callbackData": "testApp1-mt-delivery",
    "notifyURL": #use the callbackURL from Step 2 (Creating the Notification Channel) as your notifyURL
    "https://api.aerframe.aeris.com/notificationchannel/v2/1234/channels/00169bb3-e0d5-e906-331e-9f50dda27cfb/callback"
  },
  "filterCriteria": "SP:*"
}

#enter the application API key returned in the create application step below
applicationApiKey = '22222222-2222-2222-2222-222222222222'
#enter the account ID below
accountId = '1234'

url = 'https://api.aerframe.aeris.com/smsmessaging/v2/' + accountId + '/outbound/testApp1/subscriptions?apiKey=' + applicationApiKey
header = {'Content-Type':'application/json'}

req = urllib.request.Request(url, json.dumps(data).encode('utf-8'), header)
response = urllib.request.urlopen(req)

print(response.read())

Response

{"callbackReference":{"notifyURL":"https:\/\/api.aerframe.aeris.com\/notificationchannel\/v2\/1234\/channels\/00169bb3-e0d5-e906-331e-9f50dda27cfb\/callback","callbackData":"testApp1-mt-delivery","notificationFormat":"JSON"},"filterCriteria":"SP:*","resourceURL":"https:\/\/api.aerframe.aeris.com\/smsmessaging\/v2\/1234\/outbound\/testApp1\/subscriptions\/002e20a5-85ab-3f2b-227e-e41a10fea20d","link":[]}
Step 4 - Create Inbound (MO) SMS Delivery Info Subscription

Request

import json, urllib.request

data = {
  "callbackReference": {
    "callbackData": "testApp1-mo", #use appShortName in the callbackData field {appShortName}
    "notifyURL": #use the callbackURL from Step 2 (Creating the Notification Channel) as your notifyURL
    "https://api.aerframe.aeris.com/notificationchannel/v2/1234/channels/00169bb3-e0d5-e906-331e-9f50dda27cfb/callback"
  },
  "criteria": "SP:*",
  "destinationAddress": ["testApp1"] #use appShortName as the destinationAddress
}

#enter the application API key returned in the create application step below
applicationApiKey = '22222222-2222-2222-2222-222222222222'
#enter the account ID below
accountId = '1234'

url = 'https://api.aerframe.aeris.com/smsmessaging/v2/' + accountId + '/inbound/subscriptions?apiKey=' + applicationApiKey
header = {'Content-Type':'application/json'}

req = urllib.request.Request(url, json.dumps(data).encode('utf-8'), header)
response = urllib.request.urlopen(req)

print(response.read())

Response

{"callbackReference":{"notifyURL":"https:\/\/api.aerframe.aeris.com\/notificationchannel\/v2\/1234\/channels\/00169bb3-e0d5-e906-331e-9f50dda27cfb\/callback","callbackData":"testApp1-mo","notificationFormat":"JSON"},"destinationAddress":["testApp1"],"criteria":"SP:*","resourceURL":"https:\/\/api.aerframe.aeris.com\/smsmessaging\/v2\/1234\/inbound\/subscriptions\/002e2068-786d-7be4-18c5-57a2a46e3afa","link":[]}
Step 5 - Send MT-SMS

Request

import json, urllib.request

data = {
"address":[
"204041234567890" #replace this number with the imsi of the destination SIM
],
"senderAddress":"testApp1", #sender address is the application short name 
"outboundSMSTextMessage":{
"message":"Hello! This is a test message." #enter the message to be sent
},
"clientCorrelator":"654321",
"senderName":"AFTestClient"
}

#enter the application API key returned in the create application step below
applicationApiKey = '22222222-2222-2222-2222-222222222222'
#enter the account ID below
accountId = '1234'

url = 'https://api.aerframe.aeris.com/smsmessaging/v2/' + accountId + '/outbound/testApp1/requests?apiKey=' + applicationApiKey
header = {'Content-Type':'application/json'}

req = urllib.request.Request(url, json.dumps(data).encode('utf-8'), header)
response = urllib.request.urlopen(req)

print(response.read())

Response

{"address":["204041234567890"],"senderAddress":"testApp1","senderName":"AFTestClient","outboundSMSTextMessage":{"message":"Hello! This is a test message."},"clientCorrelator":"654321","resourceURL":"https:\/\/api.aerframe.aeris.com\/smsmessaging\/v2\/1234\/outbound\/testApp1\/requests\/00003558-a8b7-7c4d-48d4-d213d08ddd63"}
Step 6A - Check delivery status of a message sent to your device

Request

import json, urllib.request


#enter the application API key returned in the create application step below
applicationApiKey = '22222222-2222-2222-2222-222222222222'
#enter the account ID below
accountId = '1234'

url = 'https://longpoll.aerframe.aeris.com/notificationchannel/v2/' + accountId +'/longpoll/00079da0-82f0-3afd-34bf-08df7b65aa14?apiKey=' + applicationApiKey
req = urllib.request.Request(url)
response = urllib.request.urlopen(req).read()

jsonResponse = json.loads(response.decode('utf-8'))

if len(jsonResponse['deliveryInfoNotification']) > 0:
    print(jsonResponse['deliveryInfoNotification'][0]['deliveryInfo'][0]['deliveryStatus'])
else:
    print('No delivery status found')

Response

'DeliveredToTerminal'
Step 6B- Read message delivery status

Request

import json, urllib.request, base64

#enter the application API key returned in the create application step below
applicationApiKey = '22222222-2222-2222-2222-222222222222'
#enter the account ID below
accountId = '1234'

url = 'https://longpoll.aerframe.aeris.com/notificationchannel/v2/' + accountId + '/longpoll/00169bb3-e0d5-e906-331e-9f50dda27cfb?apiKey=' + applicationApiKey

req = urllib.request.Request(url)
response = urllib.request.urlopen(req).read()

jsonResponse = json.loads(response.decode('utf-8'))

if len(jsonResponse['inboundSMSMessageNotification']) > 0:
    
    print('Message is: '+ base64.b64decode(jsonResponse['inboundSMSMessageNotification'][0]['inboundSMSMessage']['message']).decode('ascii'))

else:
    print('No message found')

Response

'Message is: Test Message'