APIs and documentation

Inbound SMS relay API

Introduction

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.

ParameterTypeRequiredLengthDescription
commandAlphanumericYes Value must be "modify"
usernameAlphanumericYes aql username
passwordAlphanumericYes aql password
numberAlphanumericYes The number you wish to modify.
action-typeAlphanumericYes See "delivery methods" below.
action-detailAlphanumericYes See "required action detail" below
return-modeBlankNo return-mode parameter
return-formatBlankNo 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>

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:

ParameterTypeRequiredLengthDescription
commandAlphanumericYes Value must be "query"
usernameAlphanumericYes aql username
passwordAlphanumericYes aql password
numberNumericYes Number you wish to query
return-modeBlankNo return-mode parameter
return-formatBlankNo 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>

Delivery methods

The following as possible delivery methods that could be used for receiving SMS via the relay.

ActionAvailable via API?Information
null-routeYesMessages are not delivered anywhere and only logged at aql.
emailYesForward the message via email.
httpgetYesForward the message via a HTTP GET request.
httppostYesForward the message via a HTTP POST request.
mvnoNoThis 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 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
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 codes

This table lists all the response codes that the gateway can return.

StatusDescription
200OK
400Bad request
401Authentication error
500Internal system error
600Invalid Command
69001Number not valid
69003action-type is invalid
69004action-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 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

DataValue
commandmodify
usernamemyusername
passwordmypassword
number44113000111
action-typehttpget
action-detailhttp://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

Back to Documentation and APIs

Follow us on Twitter

Like us on Facebook

Connect to us on LinkedIn

Where we are

aql
13-15 Hunslet Road
Leeds
LS10 1JQ
Telephone 01133 20 30 40