SMS API: Difference between revisions

From AAISP Support Site
(Created page with "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 e...")
 
mNo edit summary
(23 intermediate revisions by 3 users not shown)
Line 1: Line 1:
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.
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.


==Inbound==
==Overview==
You can send SMS messages using our web form or our simple API.
This is where text messages are sent to us to delivery to our customers. We provide VoIP numbers in all UK area codes and some special services (e.g. 0800). However, at present, only a few of the numbers starting 01 and 02 can receive texts properly from most networks. All of our 01, 02 and 03 numbers can receive texts from Three properly. Attempts to send texts to other geographic numbers (i.e. those starting 01 and 02) cause a call to be made and the text read out by an automated system.


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.
Where texts can be received properly, and this includes all cases where A&A customers send texts through us, the text will be sent on to you by your choice of means. This is based on the incoming text setting on the control pages for your number.


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.
===Email===
If you simply put in an email address, then the text is emailed to you. Additional email headers may be present to specify fields such as User Data Header if present, etc. This is also the default if you do not put any incoming text handling in to the control pages, but you have an email address defined for the number.


===SIP2SIM===
==Inbound==
[[File:InboundSMS.png|none|frame|Inbound SMS option on Control Pages]]
If you include a 19 digit string starting 89 which is the SIM ICCID for one of your SIP2SIM cards then the text will be passed to the SIM directly as a normal text. SIP2SIM charges apply for the SIP2SIM side as an incoming text.

===Email===
You may specify an email address and we'll send the messages by email.


===HTTP===
===HTTP===
If you put an entry starting http:// or https:// then we will attempt to send the text to you using HTTP (or HTTPS). 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. If the URL does not, then an HTTP POST is done using URL encoded form data.
If you put an entry starting http:// or https:// then we will attempt to send the SMS to you using HTTP (or HTTPS). 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. If the URL does not, 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.


{| class="wikitable"
{|
|+Inbound SMS API Fields
|-
! username
! username
| This is the phone number as shown on the control pages for your VoIP number in full international format with no spaces.
| This is the phone number as shown on the control pages for your VoIP number in full international format with no spaces.
Line 48: Line 52:
| Email address or URL for delivery report, see below
| Email address or URL for delivery report, see below
|}
|}

You will note that we have tried to use field names to match GSM 03.40 values. Other values may be included. For legacy reasons you can prefix the URL specified with a * to also send the older field names of timestamp, originator, destination, 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.

The response text starts with either ERR: and an error message or OK:

example:
https://your.domain/yourscript.ext

We will then post or get using the field names as above.

==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.

To send texts you need to issue an HTTP GET or POST to our outbound text gateway https://sms.aa.net.uk/sms.cgi with the following fields as if sent from a form. As the password is sent in plain text you may prefer to use https.

{|class="wikitable"
|+OUtbound SMS API Fields
|-
! 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 <tt>username</tt> 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.
|- class="e pro"
| ''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, see below
|-
| ''oa''
| Sets the sending number (see below). Normally not needed as your <tt>username</tt> 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. Add &xml to the URL.

===Example===

Example, using curl on linux:
<syntaxhighlight lang="bash">
curl --silent --get --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>
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.



[[Category:SMS]]

Revision as of 13:29, 21 May 2021

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.

Inbound

Inbound SMS option on Control Pages

Email

You may specify an email address and we'll send the messages by email.

HTTP

If you put an entry starting http:// or https:// then we will attempt to send the SMS to you using HTTP (or HTTPS). 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. If the URL does not, 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.

Inbound SMS API Fields
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, see below
oa Sets the sending number (see below). Normally not needed as your username is used.
udh Hex UDH header, see below.
srr Email address or URL for delivery report, see below

You will note that we have tried to use field names to match GSM 03.40 values. Other values may be included. For legacy reasons you can prefix the URL specified with a * to also send the older field names of timestamp, originator, destination, 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.

The response text starts with either ERR: and an error message or OK:

example:

https://your.domain/yourscript.ext

We will then post or get using the field names as above.

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.

To send texts you need to issue an HTTP GET or POST to our outbound text gateway https://sms.aa.net.uk/sms.cgi with the following fields as if sent from a form. As the password is sent in plain text you may prefer to use https.

OUtbound SMS API Fields
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, see below
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. Add &xml to the URL.

Example

Example, using curl on linux:

curl --silent --get --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.