Send and Receive SMS
API Interface: HTTPS Resource: SMS Submit, Deliver URI: /20100101/sms/submit/ Methods: POST Response Schemas: JSON (default), XML
An application programming interface for connecting external applications, systems, and devices with the Aerialink Service Gateway for the purpose of sending and/or receiving SMS (Text Messages), MMS (Multimedia Messages), or Data (Binary) content between an application service and a mobile wireless handset or device operating on any approved wireless carrier. This specific API covers SMS messages only.
Note: Reference URI (Uniform Resource Identifier) defaults to a XML response schema.
Method [POST] : Sending an SMS Message
This method is used to send an SMS message from your application to the Aerialink Gateway which will be delivered to the end users mobile phone. The request is initiated by your application.
The following request parameters are available for this resource and method
The source code for the message. This must match to one of your codes associated with your connection.
The destination number that you want to send the SMS message to. Aerialink accepts almost any format while in “friendly format” mode (see the parameter destinationFormat below). The recommendation for US based numbers is the 11 digit format: “13105551212”.
The SMS message text that you are sending to the end user handset device. This is limited to the general standard of 160 characters unless concatenation is enabled on your account. In some cases your character limit may be less depending on your specific use case and configuration or a carrier limitation.
Defaults to 0 for “friendly format” which is the default. If this parameter is passed with a value of 1 then Aerialink will expect the destination number in “international format” with the country code (ex. “xXXXxxxXXXX”). This is required for any international messaging.
Use this parameter when you need your MT (mobile terminate) SMS to be directed to a specific port on the mobile handset device. This parameter should not be passed when sending standard SMS Text messages that are intended for the end user to read.
Use this parameter to specify a program ID that is directly related to an approved and certified program or campaign with the carrier/operators when you need your MT (mobile terminate) SMS. Typically this parameter is not required. Please check with your implementation manager if you have any questions.
An optional parameter that can be set with any user defined value. The value specified will be returned in the XML response. This is useful for threaded application architecture. This value has no impact on how your transaction is processed.
The parameters or elements returned in the response to an API request.
The requested version of the resource
The requested resource name
The method for the request. This will always be one of the following; GET, POST, UPDATE, DELETE
The request type; Syncronous or Asyncronous
The globally unique transaction ID for the message
Operating company directory number
<?xml version="1.0" encoding="UTF-8"?> <aerialink method="submit" version="20100101"> <sms> <transactionGUID>XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX</transactionGUID> <status>XX</status> <userData>YY</userData> </sms> </aerialink>
Method [POST] : Receiving an SMS Message
This method is used when Aerialink delivers a message from an end user mobile phone or device to your application. The request is initiated by Aerialink
The following request parameters are sent via an HTTP POST to the URL that you have defined in your connection/route. This can be configured or modified within the Aerialink Platform Portal.
The globally unique transaction ID for the message.
The source address for the message. This is the end user mobile phone which sent you the message.
The destination number that the end user sent the message to. This will match with a Short/Long Code configured on your account.
The SMS message text that the end user sent to your Short/Long Code. This is limited to the general standard of 160 characters unless concatenation is enabled on your account. In some cases your character limit may be less depending on your specific use case and configuration or a carrier limitation.
Applies only to Concatenated Messages. The reference number for the concatenated message related segments.
Applies only to Concatenated Messages. The total number of segments for a particular concatenated message.
Applies only to Concatenated Messages. The sequence number for the concatenated message segment.
Response (Synchronous or Aynchronous)
Aerialink expects to receive an HTTP status code of 200 from your application server which confirms your receipt of the HTTP POST. If we do not receive this HTTP status code our network will continue to retry the callback to your application until the pre-defined expiration period.
Status & Error Codes
For status codes related to Availability, Access, Security and Authentication, see HTTP Status Codes. HTTP Status Codes are consistent for all API resources.
Once your application has received an HTTP Status Code of 200 or 202 it signifies that you were able to successfully reach the Aerialink network and pass the preliminary security checks. At this point, you should expect to receive one of the following three API responses strings:
API Success Reponse “XML Packet”
This XML response will be formated as described above and will include one of the following transaction status codes.
10 (SUCCESS): Message has been successfully queued for delivery in the Aerialink network.
In almost all cases this will be the initial status code that will be returned.
20 (SUCCESS): Message was processed and delivered to the operator network for delivery to the handset.
In almost all cases this status will only be available after the initial request and response lifecycle for the transaction using our separate status API.
API Processing or Rejection Error “XML Packet”
- 50 (ERROR): Destination number is not a valid format.
- 51 (ERROR): Transaction Message Text is greater than the allowed maximum of 160 characters.
- 52 (ERROR): Transaction has been blocked by the Aerialink “End User Firewall.”
- 55 (ERROR): Transaction was completed, but the carrier did not provide an initial confirmation or transaction confirmation. The transaction may still have been successful, but a manual trace would be required to confirm.
API Negotiation Error “Simple String”
- Error Code (XXXX): This “Simple String” response will include a system error code.
An error has occurred with your request. Please try again or contact support. Error Code: XXXX,1234567890123
For a complete list of API Error Codes for this and other API resources, see API Error Codes.
If you are having trouble authenticating with the Aerialink API, verify that you have constructed the request URL properly and have prepared your authentication properly. See Base URL and Authentication for details.
You can view the API Authentication Error Log under Reports in the APi section of the Platform portal. This will confirm whether your authentication requests are being rejected or not.
If you require any additional assistance, please use one of these methods to contact the Aerialink Support Team.
This page was last updated 1515185923000