This article describes how to use Postman to send and receive SMS messages using AerFrame APIs.
In this article:
Basics
Aeris supports communication with your devices via mobile-originated (MO) and mobile-terminated (MT) SMS, using a set of APIs called AerFrame. AerFrame can be accessed with any client that supports REST APIs.
- Does not require a VPN because it is available over the public internet.
- Can not send SMS to external numbers.
Security Benefits
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:
- Global SIM is only direct delivery.
- Dual Mode A-LH supports MT-SM Store-and-Forward.
- Dual-Mode A-LH, Global SIM, and City SIM support SMS for the AerFrame v2 API.
After a message is retrieved, it is purged from the system and no longer available.
AerFrame Process Flow
The following image outlines the AerFrame API process flow.

Send/Receive SMS using AerFrame
This section outlines the following steps to send and receive SMS using the AerFrame API in Postman:
Note: Many of the REST client identifiers include placeholders, which are denoted
with open and close brackets {...}
. For the API to accept your request, you
must remove the brackets and enter the noted information for your app.
To access the AerFrame API, you need the following identifiers:
-
Account ID: Displayed in parenthesis beside the account name on the top-right
corner of the Account pop-up. For example, if your account name is ABC Ltd and
Account ID is
2XXXX
, the account name appears as ABC Ltd (2XXXX). - Account API Key: Unique API key for your account.
To access your Account ID and Account API Key:
- In the left-side menu, click Account. This opens a pop-up menu that displays
your Account ID in parenthesis.
- Click Manage API Keys to open the API Key Management screen, which enables you to view, create, edit, and delete your account's API keys.
- Your Account API keys appear in the API Key Management table.
Note: Your API key must include AerFrame as a supported function. To view an API key's supported functions, click the + icon to the left of the API key.
For more information, see Manage API Keys.
Creating an SMS Application
To create an SMS application in Postman:
- Open a new tab in Postman and set the request type to POST:
- 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}
- Select the Body tab, set the type to raw, and ensure JSON is
selected:
- 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}" }
- 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.
Creating a Notification Channel
- Open a new tab in Postman and set the request type to POST.
- Enter the following URL and replace
{accountID}
and{accountAPIkey}
with your account ID and account API key:https://api.aerframe.aeris.com/notificationchannel/v2/{accountID}/channels?apiKey={accountAPIkey}
- Select the Body tab, set the type to raw, and ensure JSON is selected.
- Enter the following raw JSON body and replace
{App Tag}
with the application tag you used in the previous request, and{Maximum Notifications}
with the maximum number of notifications:{ "applicationTag":"{App Tag}", "channelData":{ "maxNotifications":"{Maximum Notifications}", "type":"nc:LongPollingData" }, "channelLifetime":"7200", "channelType":"LongPolling", "clientCorrelator":"1234" }
- Click Send. A successful response Status is 200 OK. The
response body should look similar to the following:
Creating an Inbound (MO) SMS Subscription
- Open a new tab in Postman and set the request type to POST.
- Enter the following URL and replace
{accountID}
and{accountAPIkey}
with your account ID and account API key:https://api.aerframe.aeris.com/smsmessaging/v2/{accountID}/inbound/subscriptions?apiKey={accountAPIkey}
- Select the Body tab, set the type to raw, and ensure JSON is selected.
- Enter the following raw JSON body and replace
{callbackURL}
with thecallbackURL
value received from the Creating a Notification Channel request:{ "callbackReference":{ "callbackData":"afmyfirstapp-mosub1", "notifyURL":"{callbackURL}" }, "criteria":"SP:*", "destinationAddress":[ "afmyfirstapp" ] }
- Click Send. A successful response Status is 201 CREATED and the
response body should look similar to the following:
Creating Outbound (MT) SMS Subscription
An outbound SMS subscription enables you to access your API application's notification channel.
To create an outbound SMS subscription:
- Open a new tab in Postman and set the request type to POST.
- 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}
- Select the Body tab, set the type to raw, and ensure JSON is selected.
- Enter the following raw JSON body and replace
{callbackURL}
with thecallbackURL
value received from the Creating a Notification Channel request above:{ "callbackReference":{ "callbackData":"afmyfirstapp-mtsub1", "notifyURL":"{callbackURL}" }, "filterCriteria":"SP:*" }
- Click Send. A successful response Status is 201 CREATED and the
response body should look similar to the following:
Sending an SMS
This section demonstrates how to send an SMS to a device on the Aeris network using the AerFrame API.
Note: Ensure your device is powered on prior to sending an SMS.
To send an SMS using AerFrame:
- Open a new tab in Postman and set the request type to POST.
- 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}
- Select the Body tab, set the type to raw, and ensure JSON is selected.
- 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 theaccountID
in Step 2.{ "address": [ "{Destination SMS Address}" ], "senderAddress": "{Your Application Short name}", "outboundSMSTextMessage": { "message":"{Your message}" }, "clientCorrelator": "1234", "senderName": "{Name of Sender}" }
- Click Send. A successful response Status is 201 CREATED and the
response body should look similar to the following:
Retrieving SMS / Notifications
This section demonstrates how to retrieve SMS sent by your devices and delivery notifications for inbound (MT) SMS:
- Open a new tab in Postman and set the request type to GET.
- 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}
- 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..." } ] }, ... ] }, ... ] }
0 Comments