SMS API: Difference between revisions
m (→HTTP) |
m (→Inbound) |
||
(20 intermediate revisions by 3 users not shown) | |||
Line 6: | Line 6: | ||
You can use these systems to send an outgoing SMS, e.g. to a friend's mobile on another network. You can also use it to send an SMS message to a SIP2SIM mobile device. |
You can use these systems to send an outgoing SMS, e.g. to a friend's mobile on another network. You can also use it to send an SMS message to a SIP2SIM mobile device. |
||
You can also control how incoming SMS messages to your number or SIM are handled. For example, an incoming SMS to you can be sent onwards to your own HTTPS script. |
You can also control how incoming SMS messages to your number or SIM are handled. For example, an incoming SMS to you can be sent onwards to your own HTTPS script. This allows multiple destinations (space separated list). |
||
==Inbound== |
==Inbound== |
||
[[File:InboundSMS.png|none|frame|Inbound SMS option on Control Pages]] |
[[File:InboundSMS.png|none|frame|Inbound SMS option on Control Pages]] |
||
You list one or more ''targets'' for your SMS, separated by a space. |
|||
⚫ | |||
We work out what type of target from the format. |
|||
⚫ | |||
The targets can also be prefixed by a special character to impact the format of how the message is sent. These are currently +, *, or !. (This is an issue for an email address that starts with one of these, but for email the * prefix does nothing, so in the rare case of an email starting with *, !, or +, prefix with a *) |
|||
⚫ | |||
⚫ | |||
===Inbound targets:=== |
|||
You can use one or many of these targets: |
|||
⚫ | |||
⚫ | |||
*The prefix format + may be used to force mobile numbers to be E.123 (+ prefix) formatted and an ISO8601 timestamp. |
|||
====Toot==== |
|||
You may specify a fediverse address, e.g. @''name''@''hostname'' to get messages as a toot (''direct mention''). |
|||
*The prefix format + may be used to force mobile numbers to be E.123 (+ prefix) formatted and an ISO8601 timestamp. |
|||
====Mobile==== |
|||
You may specify a mobile number (no spaces) to forward an SMS to another number (chargeable). |
|||
⚫ | |||
If you put an entry starting http:// or https:// then we will attempt to send the SMS to you using HTTP (or HTTPS). We recommend https for privacy. |
|||
⚫ | If the URL ends with a ? or & then an HTTP GET is done with a set of form fields (i.e. name=value) containing information about the text. Using & allows you to add some specific fields first (which may be sensible to test the HTTP request came from us). If the URL does not end ? or &, then an HTTP POST is done using URL encoded form data. |
||
The fields posted are as follows, but additional fields may be added from time to time. |
The fields posted are as follows, but additional fields may be added from time to time. |
||
Line 22: | Line 41: | ||
|+Inbound SMS API Fields |
|+Inbound SMS API Fields |
||
! scts |
! scts |
||
| Service Centre Time Stamp |
| Service Centre Time Stamp in ISO8601 format |
||
|- |
|- |
||
! da |
! da |
||
| This is the number to which the message |
| This is the number to which the message was sent to (your number). International format number. |
||
|- |
|- |
||
! ud |
! ud |
||
Line 33: | Line 52: | ||
| The sending number (see below). |
| The sending number (see below). |
||
|- |
|- |
||
! |
! ''via'' |
||
| (If relayed) the original ''da'' if the message has been forwarded by us from one mobile number to another. |
|||
| Hex UDH header, see below. |
|||
|- |
|- |
||
! |
! ''udh'' |
||
| |
| (If present) Hex UDH header, see below. |
||
|- |
|- |
||
! dcs |
! ''dcs'' |
||
| Data Coding Scheme which we provide in decimal (its a byte) |
| (If not zero) Data Coding Scheme which we provide in decimal (its a byte) |
||
|- |
|- |
||
! pid |
! ''pid'' |
||
| Protocol Identifier which we provide in decimal (its a byte) |
| (If not zero) Protocol Identifier which we provide in decimal (its a byte) |
||
|} |
|} |
||
⚫ | |||
Naming comes from: https://en.wikipedia.org/wiki/GSM_03.40 |
|||
⚫ | |||
We support UTF-8 coding of the full GSM 7 bit character set (including £$¥èéùìòÇØøÅåΔ_ΦΓΛΩΠΨΣΘΞÆæÉÄÖÑܧäöñüà€¡¿). Whilst one message is normally up to 160 characters some characters are coded using two characters using an ESC prefix in the 7 bit alphabet (€,[,\,],^,{,|,},~). The message will be coded as 7, 8 or 16 bit depending on what you include in the text, and this will impact the number of message parts that may be sent. If you include the invalid UTF-8 sequence 0xC0 0x80, then that includes a null in the message. If you include any unicode characters beyond U+0xFFFF then UTF-16 coding is used and sending of text in is UCS2 format. Not all interconnects or devices understand UTF-16 format. |
|||
*The prefix format * may be used to also send the older field names of ''timestamp'', ''originator'', ''destination'', ''message'', but we recommend updating your scripts to use the new field names. |
|||
The response text starts with either ERR: and an error message or OK: |
|||
We support UTF-8 coding of the full GSM 7 bit character set (including £$¥èéùìòÇØøÅåΔ_ΦΓΛΩΠΨΣΘΞÆæÉÄÖÑܧäöñüà€¡¿) and from UCS16 messages and UTF-16 surrogates. Not all of our SMS interconnects handle all of the coding, so we send the message as best we can. |
|||
example: |
|||
https://your.domain/yourscript.ext |
|||
===SIM=== |
|||
We will then post or get using the field names as above. |
|||
Where we offer SIM services (e.g. SIP2SIM) you can simply put the ICCID (long number starting 89) of the target SIM to have it delivered to the SIM. |
|||
==Outbound messages== |
==Outbound messages== |
||
We operate an outbound text service that is available to all of our customers that have a VoIP number. To use this service you must have an outgoing password configured in the control pages for the VoIP number. |
We operate an outbound text service that is available to all of our customers that have a VoIP number. To use this service you must have an outgoing password configured in the control pages for the VoIP number. |
||
Our SMS gateway is https://sms.aa.net.uk/sms.cgi and uses with the following fields. |
|||
*These can be sent as a URL encoded form data GET |
|||
*These can be sent as a URL encoded form data POST |
|||
*These can be sent as fields in a POST of a JSON object |
|||
{|class="wikitable" |
{|class="wikitable" |
||
|+ |
|+Outbound SMS API Fields |
||
|- |
|- |
||
! username |
! username |
||
Line 86: | Line 104: | ||
|- |
|- |
||
| ''private'' |
| ''private'' |
||
| Marks the message as private, |
| Marks the message as private, such that it is not included in the itemises billing. |
||
|- |
|- |
||
| ''oa'' |
| ''oa'' |
||
Line 97: | Line 115: | ||
| Email address or URL for delivery report, see below |
| Email address or URL for delivery report, see below |
||
|} |
|} |
||
Note that we have, again, tried to use GSM 03.40 field names, but alternative field names are supported for now: destination, originator, message. |
Note that we have, again, tried to use GSM 03.40 field names, but alternative field names are supported for now: ''destination'', ''originator'', ''message''. |
||
We support UTF-8 coding of the full GSM 7 bit character set (including £$¥èéùìòÇØøÅåΔ_ΦΓΛΩΠΨΣΘΞÆæÉÄÖÑܧäöñüà€¡¿). Whilst one message is normally up to 160 characters some characters are coded using two characters using an ESC prefix in the 7 bit alphabet (€,[,\,],^,{,|,},~). The message will be coded as 7, 8 or 16 bit depending on what you include in the text, and this will impact the number of message parts that may be sent. If you include the invalid UTF-8 sequence 0xC0 0x80, then that includes a null in the message. If you include any unicode characters beyond U+0xFFFF then UTF-16 coding is used and sending of text in is UCS2 format. Not all interconnects or devices understand UTF-16 format. |
We support UTF-8 coding of the full GSM 7 bit character set (including £$¥èéùìòÇØøÅåΔ_ΦΓΛΩΠΨΣΘΞÆæÉÄÖÑܧäöñüà€¡¿). Whilst one message is normally up to 160 characters some characters are coded using two characters using an ESC prefix in the 7 bit alphabet (€,[,\,],^,{,|,},~). The message will be coded as 7, 8 or 16 bit depending on what you include in the text, and this will impact the number of message parts that may be sent. If you include the invalid UTF-8 sequence 0xC0 0x80, then that includes a null in the message. If you include any unicode characters beyond U+0xFFFF then UTF-16 coding is used and sending of text in is UCS2 format. Not all interconnects or devices understand UTF-16 format. |
||
Line 105: | Line 123: | ||
The response text starts either ERR: and an error message or OK: |
The response text starts either ERR: and an error message or OK: |
||
You can choose to have a response back in XML - this makes the service more compatible with Acrobits' Groundwire mobile phone app that is a softphone with SMS capability. |
You can choose to have a response back in XML - this makes the service more compatible with Acrobits' Groundwire mobile phone app that is a softphone with SMS capability. Include a field called xml, e.g. add &xml to the URL for a GET. |
||
===Example=== |
===Example=== |
||
Line 111: | Line 129: | ||
Example, using curl on linux: |
Example, using curl on linux: |
||
<syntaxhighlight lang="bash"> |
<syntaxhighlight lang="bash"> |
||
curl --silent |
curl --silent --form-string username=01234567890 --form-string password=123456 --form-string da=01234567890 --form-string ud="Hello world" https://sms.aa.net.uk/sms.cgi |
||
</syntaxhighlight> |
</syntaxhighlight> |
||
Messages are charged per message part, see our main website for prices. |
Messages are charged per message part, see our main website for prices. |
Revision as of 10:27, 25 June 2024
This page contains technical details and as such may be quite long and hard to follow. If you cannot find the details you require please feel free to contact support who can explain things for you. You will also find many other customers on irc who can help with queries. Feel free to send us feedback if you think there are any errors in this page.
Overview
You can send SMS messages using our web form or our simple API.
You can use these systems to send an outgoing SMS, e.g. to a friend's mobile on another network. You can also use it to send an SMS message to a SIP2SIM mobile device.
You can also control how incoming SMS messages to your number or SIM are handled. For example, an incoming SMS to you can be sent onwards to your own HTTPS script. This allows multiple destinations (space separated list).
Inbound
You list one or more targets for your SMS, separated by a space. We work out what type of target from the format.
The targets can also be prefixed by a special character to impact the format of how the message is sent. These are currently +, *, or !. (This is an issue for an email address that starts with one of these, but for email the * prefix does nothing, so in the rare case of an email starting with *, !, or +, prefix with a *)
Inbound targets:
You can use one or many of these targets:
You may specify an email address, e.g. localpart@hostname and we'll send the messages by email.
- The prefix format + may be used to force mobile numbers to be E.123 (+ prefix) formatted and an ISO8601 timestamp.
Toot
You may specify a fediverse address, e.g. @name@hostname to get messages as a toot (direct mention).
- The prefix format + may be used to force mobile numbers to be E.123 (+ prefix) formatted and an ISO8601 timestamp.
Mobile
You may specify a mobile number (no spaces) to forward an SMS to another number (chargeable).
HTTP
If you put an entry starting http:// or https:// then we will attempt to send the SMS to you using HTTP (or HTTPS). We recommend https for privacy.
If the URL ends with a ? or & then an HTTP GET is done with a set of form fields (i.e. name=value) containing information about the text. Using & allows you to add some specific fields first (which may be sensible to test the HTTP request came from us). If the URL does not end ? or &, then an HTTP POST is done using URL encoded form data.
The fields posted are as follows, but additional fields may be added from time to time.
scts | Service Centre Time Stamp in ISO8601 format |
---|---|
da | This is the number to which the message was sent to (your number). International format number. |
ud | This is the message, encoded in UTF-8. |
oa | The sending number (see below). |
via | (If relayed) the original da if the message has been forwarded by us from one mobile number to another. |
udh | (If present) Hex UDH header, see below. |
dcs | (If not zero) Data Coding Scheme which we provide in decimal (its a byte) |
pid | (If not zero) Protocol Identifier which we provide in decimal (its a byte) |
You will note that we have tried to use field names to match GSM 03.40 values. Other values may be included.
- The prefix format * may be used to also send the older field names of timestamp, originator, destination, message, but we recommend updating your scripts to use the new field names.
We support UTF-8 coding of the full GSM 7 bit character set (including £$¥èéùìòÇØøÅåΔ_ΦΓΛΩΠΨΣΘΞÆæÉÄÖÑܧäöñüà€¡¿) and from UCS16 messages and UTF-16 surrogates. Not all of our SMS interconnects handle all of the coding, so we send the message as best we can.
SIM
Where we offer SIM services (e.g. SIP2SIM) you can simply put the ICCID (long number starting 89) of the target SIM to have it delivered to the SIM.
Outbound messages
We operate an outbound text service that is available to all of our customers that have a VoIP number. To use this service you must have an outgoing password configured in the control pages for the VoIP number.
Our SMS gateway is https://sms.aa.net.uk/sms.cgi and uses with the following fields.
- These can be sent as a URL encoded form data GET
- These can be sent as a URL encoded form data POST
- These can be sent as fields in a POST of a JSON object
username | This is the phone number as shown on the control pages for your VoIP number in full international format with no spaces. |
---|---|
password | The corresponding outgoing password for the username as set in the control pages for your VoIP number. |
da | This is the number to which the message is to be sent and should be a full international format number (however, national format is also accepted). This may be a SIP2SIM ICCID to send direct to a SIM. |
ud | This is the message to send, encoded in UTF-8. |
limit | Set this to limit the number of parts that the message may be sent in. |
costcentre | Optional, up to 10 characters, code that is included in the bill XML data. |
private | Marks the message as private, such that it is not included in the itemises billing. |
oa | Sets the sending number (see below). Normally not needed as your username is used. |
udh | Hex UDH header, see UDH messages. |
srr | Email address or URL for delivery report, see below |
Note that we have, again, tried to use GSM 03.40 field names, but alternative field names are supported for now: destination, originator, message.
We support UTF-8 coding of the full GSM 7 bit character set (including £$¥èéùìòÇØøÅåΔ_ΦΓΛΩΠΨΣΘΞÆæÉÄÖÑܧäöñüà€¡¿). Whilst one message is normally up to 160 characters some characters are coded using two characters using an ESC prefix in the 7 bit alphabet (€,[,\,],^,{,|,},~). The message will be coded as 7, 8 or 16 bit depending on what you include in the text, and this will impact the number of message parts that may be sent. If you include the invalid UTF-8 sequence 0xC0 0x80, then that includes a null in the message. If you include any unicode characters beyond U+0xFFFF then UTF-16 coding is used and sending of text in is UCS2 format. Not all interconnects or devices understand UTF-16 format.
Response
The response text starts either ERR: and an error message or OK:
You can choose to have a response back in XML - this makes the service more compatible with Acrobits' Groundwire mobile phone app that is a softphone with SMS capability. Include a field called xml, e.g. add &xml to the URL for a GET.
Example
Example, using curl on linux:
curl --silent --form-string username=01234567890 --form-string password=123456 --form-string da=01234567890 --form-string ud="Hello world" https://sms.aa.net.uk/sms.cgi
Messages are charged per message part, see our main website for prices.
Delivery reports
In some cases we can provide a delivery report and indicate progress of a message. However this is not always possible and should not be relied on.
To use this, specify the srr either as an email address or a URL. The URL can include (typically after the ?) a string %code which will be replaced with a number that indicates progress. 1=Delivered, 2=Rejected, 4=Buffered, 8=Accepted by SMSC, and 16=Rejected by SMSC. Other % strings can be used such as %da or %dest as the original destination number, %oa for originator, %ud for the message.