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></date_format>
        <shortcode></shortcode>
        <keyword></keyword>
    </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.

""

🚧

All entries marked with * are mandatory

The output returned will be a data set or XML in the following format:

<api_result>
    <data>
        <changeid></changeid>
        <shortcode></shortcode>
        <keyword></keyword >
        <phonenumber></phonenumber>
        <message></message>
        <received></received>
    </data>
    <call_result>
        <result></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.