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:

XML

<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:

XML

<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