Inbound SMS relay API
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.
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.
Modify the number
Request
If you wish to adjust the SMS delivery mechanism for a number, you need to provide the
following parameters to the API.
| Parameter | Type | Required | Length | Description |
|---|---|---|---|---|
| Command | Alphanumeric | Yes | Value must be “modify” | |
| Username | Alphanumeric | Yes | aql username | |
| Password | Alphanumeric | Yes | aql password | |
| Number | Alphanumeric | Yes | The number you wish to modify | |
| Action-type | Alphanumeric | Yes | See “delivery methods” below | |
| Action-detail | Alphanumeric | Yes | See “required action detail” below | |
| Return-mode | Blank | No | See separate return-mode parameters document | |
| Return-format | Blank | No | See separate return-mode parameters document |
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>
Query number
Request
If you wish to query the current SMS delivery mechanism for a number, you need to provide the following parameters to the API:
| Parameter | Type | Required | Length | Description |
|---|---|---|---|---|
| Command | Alphanumeric | Yes | Value must be “query” | |
| Username | Alphanumeric | Yes | aql username | |
| Password | Alphanumeric | Yes | aql password | |
| Number | Alphanumeric | Yes | The number you wish to query | |
| Return-mode | Blank | No | See separate return-mode parameters document | |
| Return-format | Blank | No | See separate return-mode parameters document |
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>
Delivery methods
The following as possible delivery methods that could be used for receiving SMS via the relay.
| 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 | This indicates the number is currently being used in conjunction
with our MVNO offering.
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. |
Required action detail
null-route
The action-detail parameter is not required for the ‘null-route’ action-type.
For all others it must be provided.
httpget and 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 in the inbound SMS to UK landline numbers API document.
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
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 codes
This table lists all the response codes that the gateway can return.
| Status | 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 |
Return mode
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 separate return-mode documentation.
Examples
Note that while the example below only uses the HTTP GET method however you can also use HTTP POST.
To modify the SMS endpoint
| Data | Value |
|---|---|
| command | modify |
| username | myusername |
| pasword | mypassword |
| number | 44113000111 |
| 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
