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. 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:
- 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