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:

  1. ShortCode_Get_DS_DS
  2. ShortCode_Get_DS_STR
  3. ShortCode_Get_DS_ZIP
  4. ShortCode_Get_STR_DS
  5. ShortCode_Get_STR_STR
  6. 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 tagDescriptionDefault
*IDThe max ChangeID from the previous call.-
Date_FormatThe format of any dates that are returned.Dd/MMM/yyyy HH:mm:ss
ShortcodeThe short code (5 digit number). If nothing is specified then all short codes are returned.0
KeywordSearch on a keyword. If a keyword has been allocated to your account eg: “test” you can specify to retrieve only these entries.""
Cols_ReturnedThe 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 tagDescription
ChangeIDThe max unique ChangeID for each incoming message.
ShortcodeThe short code (5 digit number).
KeywordIf the shortcode has been separated on a keyword. it will be displayed.
Each keyword can have its own properties.
PhonenumberThe number the message was received from.
MessageThe message received.
ReceivedThe date the message was received.
mncThe Mobile Network Code
mccThe Mobile Country Code