All aql® numbers support inbound SMS messaging. To provide the maximum flexibility to your business, we provide this API to allow you full
control over how and where these SMS messages are delivered.
The different methods of delivery are:
| Action | Available via API? | Information |
|---|---|---|
| null-route | yes | Messages are not delivered anywhere and only logged at aql |
| yes | Forward the message via email | |
| httpget | yes | Forward the message via a HTTP GET request |
| httppost | yes | Forward the message via a HTTP POST request |
| mvno | no – read only | This indicates the number is currently being used in conjunction with our MVNO offering. See notes below |
If the action type of a number is currently set to 'mvno', this means that the messages cannot be forwarded to any external
destination.
In addition, if you modify the action type from 'mvno' to some other method of delivery, this will mean that MT messages will no longer be
delivered to the MVNO sim this number is associated with. They will, however, be delivered to the destination you set.
It is important to note that you are NOT able to set the action type of any number to 'mvno'.
aql® cannot be held responsible for any non-delivery of MVNO messages caused this kind of modification.
Access to the SMS Relay API is via the following gateway URL:
https://gw.aql.com/sms/sms-relay.api.php
The gateway accepts both HTTP GET and POST
If you wish to adjust the SMS delivery mechanism for a number, you need to provide the following parameters to the API:
Request
| Variable name | Requirement | Value |
|---|---|---|
| username | mandatory | Account username |
| password | mandatory | Account password |
| command | mandatory | modify |
| number | mandatory | Number you wish to modify |
| action-type | mandatory | The 4 options available are: null-route httpget httppost |
| action-detail | Depends on action-type. See notes below | Depends on action-type. See notes below |
| return-mode | optional | return-mode parameter |
| return-format | optional | return-mode parameter |
The action-detail parameter is not required for the 'null-route' action-type. For all others it must be provided.
action-type: 'httpget' / 'httppost'
In this case, action-detail must be a callback URL. If you wish to provide more than 1 callback URL, please separate them by commas. If
multiple URLs are provided, successive URLs will only be called if the previous URL could not be contacted.
There are message specific variables which can embedded within your URL(s). All possible values can be found at
https://www.aql.com/sms/landline-number/developers/.
e.g.
http://www.yourdomain.co.uk/callback.php?id=%i&orig=%o&msg=%m
http://www.domain-backup.co.uk/callback.php?id=%i&orig=%o&msg=%m
action-type: 'email'
In this case the action-detail parameter must be a list of email addresses. Each email address will be sent a copy of the message.
Response
If the request was successful, the following will be returned (unless return-mode is set to 'url')
<status_code>: <description>
number: <number>
action-type: <action-type>
action-detail: <action-detail>
If the request failed for any reason, the following will be returned
<status_code>: <description>
If you wish to query the current SMS delivery mechanism for a number, you need to provide the following parameters to the API:
Request
| Variable name | Requirement | Value |
|---|---|---|
| username | mandatory | Account username |
| password | mandatory | Account password |
| command | mandatory | query |
| number | mandatory | Number you wish to query |
| return-mode | optional | return-mode parameter |
| return-format | optional | return-mode parameter |
Response
If the request was successful, the following will be returned (unless return-mode is set to 'url')
<status_code>: <description>
number: <number>
action-type: <action-type>
action-detail: <action-detail>
If the request failed for any reason, the following will be returned:
<status_code>: <description>
This table lists all the error codes that the gateway can return:
| Errorcode | Description |
|---|---|
| 200 | OK |
| 400 | Bad request |
| 401 | Authentication error |
| 500 | Internal system error |
| 600 | Invalid Command |
| 69001 | Number not valid |
| 69003 | action-type is invalid |
| 69004 | action-detail is invalid for the provided action-type |
To make the API more flexible, you can set the format of the response. For further information on setting the return-mode and return-format parameters, please see the following page:
Note: the example only uses the HTTP GET method however you can also use HTTP POST.
To modify the sms endpoint
| Data | value |
|---|---|
| username | myusername |
| password | mypassword |
| number | 44113000111 |
| command | modify |
| action-type | httpget |
| action-detail | http://www.yourdomain.co.uk/callback.php?id=%i&orig=%o&msg=%m |
You would need to assemble the following
https://gw.aql.com/sms/sms-relay.api.php?username=myusername&password=mypassword&command=modify&number=44113000111&action-type=httpget&action-detail=http%3A%2F%2Fwww.yourdomain.co.uk%2Fcallback.php%3Fid%3D%25i%26orig%3D%25o%26msg%3D%25m
If the request was successful, you would get a result similar to:
status: 200
number: 44113000111
action-type: httpget
action-detail: http://www.yourdomain.co.uk/callback.php?id=%i&orig=%o&msg=%m
If the request was not successful, you would get a response similar to:
69001: number is invalid
