Retrieve Incoming Short Code Entries
The SMS gateway is designed to allow easy retrieval of your inbound messages (shortcodes).
The design allows the following:
- Retrieval of items you have not already pulled
- Instant retrieval of data (due to API table design and indexing)
- Customisable result formatting
- Prevention of timeouts
So how is this achieved?
The API system uses a unique identity field called “changeid”, which is permanently incrementing.
When an inbound message is received from the corresponding network, a new record is written to the API and the changeid will increment by 1.
In the result set, the element “changeid” will be present along with the other elements you have specified. This needs to be stored and the maximum changeid utilised by the next call. The following is occurring within the SMS gateway:
“Select top 100 * from Short Code_Table where ID > @ID order by ID asc”
There are 6 methods available for retrieving replies:
- ShortCode_Get_DS_DS
- ShortCode_Get_DS_STR
- ShortCode_Get_DS_ZIP
- ShortCode_Get_STR_DS
- ShortCode_Get_STR_STR
- ShortCode_Get_STR_ZIP
Each function accepts 3 parameters:
- Username (string)
- Password (string)
- XML string or data set (depending on the function you choose)
The XML object looks like this:
<options>
<settings>
<id>0</id>
<date_format>Dd/MMM/yyyy HH:mm:ss</date_format>
<shortcode>unique5digitnumber</shortcode>
<keyword></keyword>
<cols_returned>changeid,shortcode,keyword,phonenumber,message,received,mnc,mcc</cols_returned>
</settings>
</options>
XML tag | Description | Default |
---|---|---|
*ID | The max ChangeID from the previous call. | - |
Date_Format | The format of any dates that are returned. | Dd/MMM/yyyy HH:mm:ss |
Shortcode | The short code (5 digit number). If nothing is specified then all short codes are returned. | 0 |
Keyword | Search on a keyword. If a keyword has been allocated to your account eg: “test” you can specify to retrieve only these entries. | "" |
Cols_Returned | The following parameters are available in any combination: changeid, shortcode, keyword, phonenumber, message, received, mnc, mcc. If nothing is specified changeid, shortcode, keyword, phonenumber, message, received will be returned as a default. | As mentioned. |
All entries marked with * are mandatory
The output returned will be a data set or XML in the following format:
<api_result>
<data>
<changeid>100</changeid>
<shortcode>unique5digitnumber</shortcode>
<keyword></keyword>
<phonenumber>2783*******</phonenumber>
<message>Testing</message>
<received>19/Jan/2024 13:40:58</received>
<mnc>01</mnc>
<mcc>655</mcc>
</data>
<call_result>
<result>True</result>
<error/>
</call_result>
</api_result>
XML tag | Description |
---|---|
ChangeID | The max unique ChangeID for each incoming message. |
Shortcode | The short code (5 digit number). |
Keyword | If the shortcode has been separated on a keyword. it will be displayed. Each keyword can have its own properties. |
Phonenumber | The number the message was received from. |
Message | The message received. |
Received | The date the message was received. |
mnc | The Mobile Network Code |
mcc | The Mobile Country Code |
Updated 8 months ago