Manage SMS Messaging with the AerFrame API

AerFrame and Short Message Peer-to-Peer (SMPP) are the only ways to send / receive SMS with Aeris devices outside of AerPort, Aeris’ web-based device management portal. There are two separate SMPP environments for SMS that support the following:

• CDMA (no longer supported by Aeris).
• Other device types (e.g., Dual-Mode A-LH, Global SIM, and City SIM).

AerFrame API supports Store-and-Forward depending on the device's provisioning and the account's configuration (i.e. if the device is configured for Store-and-Forward). Store-and-Forward is not a function of the API but of the device service and provisioning. For example:

After a message is retrieved, it is purged from the system and no longer available.

To create an SMS application in Postman:

1. Open a new tab in Postman and set the request type to POST:

   

2. Enter the following URL and replace {accountID} and {accountAPIkey} with your Account ID and Account API Key:

   https://api.aerframe.aeris.com/registration/v2/{accountID}/applications?apiKey={accountAPIkey}

3. Select the Body tab, set the type to raw, and ensure JSON is selected:

   

4. Enter the following JSON body and replace each item in {} with the appropriate information for your app:

   Note: The applicationShortName must not contain any spaces.

   { 
   "applicationName":"{App Name}", 
   "applicationShortName":"{AppShortName}", 
   "applicationTag":"{App Tag}", 
   "description":"{description}" 
   } 

   

5. Click Send. A successful response Status is 201 Created and the response body should look similar to the following:

   

Notes:

• The apiKey is not the same as your account API key.
• The GUID at the end of the resourceURL (e.g. 27585) is the app's resource key.

An outbound SMS subscription enables you to access your API application's notification channel.

To create an outbound SMS subscription:

1. Open a new tab in Postman and set the request type to POST.
2. Enter the following URL and replace {accountID}, {applicationShortName}, and {accountAPIkey} with your account ID, application short name, and account API key:

   https://api.aerframe.aeris.com/smsmessaging/v2/{accountID}/outbound/{applicationShortName}/subscriptions?apiKey={accountAPIkey}

3. Select the Body tab, set the type to raw, and ensure JSON is selected.
4. Enter the following raw JSON body and replace {callbackURL} with the callbackURL value received from the Creating a Notification Channel request above:

   { 
   "callbackReference":{ 
   "callbackData":"afmyfirstapp-mtsub1", 
   "notifyURL":"{callbackURL}" 
   }, 
   "filterCriteria":"SP:*" 
   } 

   

5. Click Send. A successful response Status is 201 CREATED and the response body should look similar to the following:

   

This section demonstrates how to send an SMS to a device on the Aeris network using the AerFrame API. Ensure the device is powered on prior to sending an SMS.

Note: You identify the destination device by its IMSI. If you are sending an SMS to an eSIM, you must first retrieve the IMSI of the active profile on the eSIM. To retrieve the IMSI, use the AerAdmin API: Single Operation - Get Device Details (Non-Structured Response), and specify the EID as the identifier. The response payload returns the ICCID, IMSI, and MSISDN of the active profile.

To send an SMS using AerFrame:

1. Open a new tab in Postman and set the request type to POST.
2. Enter the following URL and replace {accountID}, {applicationShortName}, and {accountAPIkey} with your account ID, application short name, and account API key:

   https://api.aerframe.aeris.com/smsmessaging/v2/{accountID}/outbound/{applicationShortName}/requests?apiKey={accountAPIkey}

3. Select the Body tab, set the type to raw, and ensure JSON is selected.
4. Enter the following raw JSON body and replace the items in {} with the appropriate information:

   Note: The Destination SMS Address is the IMSI of the device where you want to send the message. The device must belong to the account specified by the accountID in Step 2.

   { 
   "address": [ 
   "{Destination SMS Address}" 
   ], 
   "senderAddress": "{Your Application Short name}", 
   "outboundSMSTextMessage": { 
   "message":"{Your message}" 
   }, 
   "clientCorrelator": "1234", 
   "senderName": "{Name of Sender}" 
   } 

   

5. Click Send. A successful response Status is 201 CREATED and the response body should look similar to the following:

   

This section demonstrates how to retrieve SMS sent by your devices and delivery notifications for inbound (MT) SMS:

1. Open a new tab in Postman and set the request type to GET.
2. Enter the following URL and replace {accountID}, {callBackURL}, and {accountAPIkey} with the account ID, the callback URL value you retrieved in the Creating a Notification Channel request, and the account API key:

   https://longpoll.aerframe.aeris.com/notificationchannel/v2/{accountID}/longpoll/{callBackURL}?apiKey={accountAPIkey}

3. Click Send. A successful response Status is 200 OK and the response body should look similar to the following:

   { 
   
     "inboundSMSMessageNotification": [], 
     "deliveryInfoNotification": [ 
       { 
         "callbackData": "afmyfirstapp-mtsub1", 
         "deliveryInfo": [ 
           { 
             "address": "310...", 
             "deliveryStatus": "DeliveredToNetwork", 
             "description": "0:null", 
             "link": [ 
               { 
                 "rel": "MTMessageRequest ResourceUrl", 
                 "href": "https://api.aerframe.aeris.com/smsmessaging/v2/2.../outbound/Short_name/requests/16..." 
               }, 
               { 
                 "rel": "MTDeliverySubscription ResourceUrl", 
                 "href": "https://api.aerframe.aeris.com/smsmessaging/v2/2.../outbound/Short_name/subscriptions/001..." 
               } 
             ] 
           }, 
           ... 
         ] 
       }, 
       ... 
     ] 
   }