Retrieve Data From the API

The SMS gateway is designed to allow easy retrieval of your outbound messages and inbound messages (replies).

RETRIEVING SENT DATA - (DATA SET AND XML)

There are 5 methods for retrieving sent items:

  • Sent_DS_DS (Accepts data set, returns data set)
  • Sent_STR_DS (Accepts XML string, returns data set)
  • Sent_STR_STR (Accepts XML string, returns XML string)
  • Sent_DS_STR (Accepts data set, returns XML string)
  • Sent_ZIP_ZIP (Accepts zipped stream, returns zipped stream)

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:

<sent>
    <settings>
        <id>0</id>
        <max_recs></max_recs>
        <cols_returned></cols_returned>
        <date_format>yyyyMMddHHmmss</date_format>
    </settings>
</sent>

Parameter

Description

Default

*ID

The max CHANGEID from the previous call. Start with “0”

Max_recs

The number of records returned from the call. Values 1 to 100

100

Cols_Returned

The xml tags returned in the result. Options are: sentid, eventid, smstype, numto, data, flash, customerid, status, statusdate. Each entry must be separated by a comma.

ChangeID

Date Format

The format of any dates that are returned.

dd/MMM/yyyy HH:mm:ss

🚧

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>
        <sentid></sentid>
        <eventid></eventid>
        <smstype></smstype>
        <numto></numto>
        <data></data>
        <flash></flash>
        <customerid></customerid>
        <status></status>
        <statusdate></statusdate>
    </data>
    <call_result>
        <result></result>
        <error/>
    </call_result>
</api_result>

XML tag

Description

changeid

A unique ID identifying the change in a message status.

sentid

A unique value for each message. You could receive the same SentID back if the message status changes.

eventid

When sending, an eventid is generated and returned in the result xml. This eventid can be for 1 or “infinity” message entries.

smstype

This is the type of message sent. (Default = SMS)

numto

The number the message was sent to.

data

The data sent to the user.

customerid

The customerid for the message when the data was sent.

status

The message status. Options are “DELIVRD”, “UNDELIV”, ”UNKNOWN”, ”EXPIRED”.

statusdate

The date and time the message was sent.

RETRIEVING REPLIES - (OVERVIEW)

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 “replyid” which is permanently incrementing. When an inbound message is received from the corresponding network, a new record is written to the API and the replyid will increment by 1.

In the result set, the element “replyid” will be present along with the other elements you have specified.
This needs to be stored and the maximum replyid utilised by the next call. The following is occurring within the SMS gateway:

“Select top 100 * from API_Reply_Table where replyid > @ID order by replyid asc”

📘

Tips

Start with id (replyid) = 0
Store the max replyid in your local system, permanently (database or IO system)
Only pull back data you require, using the “cols_returned” element (this will reduce bandwidth).

🚧

Limitations

Inbound messages are only retained for up to seven days, i.e. replies that were sent more than a week ago cannot be retrieved via Web Services.

Only replies to messages that were sent via Web Services, and from the account that was used for authentication, can be retrieved. E.g. sub accounts cannot retrieve each other’s messages, and replies to messages sent via FTP cannot be retrieved via Web Services.

RETRIEVING REPLIES - (DATA SET AND XML)

There are 5 methods for retrieving replies:

  • Reply_DS_DS (Accepts data set, returns data set)
  • Reply_STR_DS (Accepts XML string, returns data set)
  • Reply_STR_STR (Accepts (XML string, returns XML string)
  • Reply_DS_STR (Accepts data set, returns XML string)
  • Reply_ZIP_ZIP (Accepts zipped stream, returns zipped stream)

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:

<reply>
    <settings>
        <id></id>
        <max_recs></max_recs>
        <cols_returned> </cols_returned>
        <date_format> </date_format>
    </settings>
</reply>

Parameter

Description

Default

*ID

The max REPLYID from the previous call

Max_recs

The number of records returned from the call. Values 1 to 100

100

Cols_Returned

The xml tags returned in the result. Options are: replyid, eventid, numfrom, receiveddata, received, sentid, sentdata, sentdatetime, sentcustomerid, optout. Each entry must be separated by a comma.

Replyid

Date Format

The format of any dates that are returned.

dd/MMM/yyyy HH:mm:ss

🚧

All entries marked with * are mandatory

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

<api_result>
    <data>
        <replyid></replyid>
        <eventid></eventid>
        <numfrom></numfrom>
        <receiveddata>123</receiveddata>
        <sentid></sentid>
        <sentdata></sentdata>
        <sentcustomerid/>
        <received></received>
        <sentdatetime></sentdatetime>
    </data>
    <call_result>
        <result></result>
        <error/>
    </call_result>
</api_result>

replyid

The max unique REPLYID for each incoming message

eventid

When sending an eventid is generated and returned in the result xml. This eventid
can be for 1 or “infinity” message entries.

numfrom

The number of the user that sent the incoming message

receiveddata

The data that the user returned

received

The date and time the message was received

sentid

The unique sentid for the outgoing message

sentdata

The data sent to the user

sentdatetime

The date and time the message was sent

sentcustomerid

The customerid for the message when the data was sent

optout

Contains the value 1 if the received data matched an opt-out phrase, or 0 if not.

Retrieving Your Group Information (Online Groups)

There are 4 methods for retrieving your groups:

  • Groups_List_DS_DS (Accepts data set, returns data set)
  • Groups_List _STR_DS (Accepts XML string, returns data set)
  • Groups_List _STR_STR (Accepts XML string, returns XML string)
  • Groups_List _DS_STR (Accepts data set, returns XML string)

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>
        <cols_returned></cols_returned>
        <date_format></date_format>
    </settings>
</options>

XML tag

Description

Default

*Cols_Returned

The xml tags returned in the result. Options are: groupname, groupdesc, groupcreated. Each entry must be separated by a comma.

Groupid

Date Format

The format of any dates that are returned.

dd/MMM/yyyy HH:mm:ss

🚧

All entries marked with * are mandatory

Example XML result:

<api_result>
    <data>
        <replyid></replyid>
        <groupid>118093</groupid>
        <groupname>the name of your group</groupname>
        <groupdesc>the desc of your group</groupdesc>
        <groupcreated>13/Apr/2009 13:00:05</groupcreated>
    </data>
    <call_result>
        <result></result>
        <error/>
    </call_result>
</api_result>

XML tag

Description

groupid

A unique GROUPID for each group in the system

Groupname

The name of your group

Groupdesc

The description you gave your group

groupcreated

When the group was created

Retrieve Your Short Code Counts

There are 4 methods for retrieving the number of messages sent to your short codes.

  • • ShortCodeCount_DS_DS (Accepts data set, returns data set)
  • • ShortCodeCount_STR_DS (Accepts XML string, returns data set)
  • • ShortCodeCount_STR_STR (Accepts XML string, returns XML string)
  • • ShortCodeCount_DS_STR (Accepts data set, returns XML string)

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>
        <start_date>01/Jan/2018</start_date>
        <end_date>10/Jan/2018</end_date>
    </settings>
    <shortcodes>
        <shortcode>XXXXX</shortcode>
    </shortcodes>
    <shortcodes>
        <shortcode>YYYYY</shortcode>
    </shortcodes>
</options>

XML tag

Description

Default

*start_date

The start date of the query period. Start_date can be set up to 12 months in the
past.

*end_date

The end date of the query period. The start_date and end_date must be between
1 and 31 days.

shortcodes

The collection of short codes. If omitted, will return all short codes assigned to
you with totals for the period.

shortcode

A short code number.

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

<api_result>
    <data>
        <shortcode>XXXXX</shortcode>
        <count>200</count>
    </data>
    <data>
        <shortcode>YYYYY</shortcode>
        <count>45</count>
    </data>
    <call_result>
        <result>True</result>
        <error/>
    </call_result>
</api_result>

XML tag

Description

shortcode

Your short code you received messages on.

count

The total count associated to the short code for the period.