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>
ParameterDescriptionDefault
*IDThe max CHANGEID from the previous call. Start with “0”-
Max_recsThe number of records returned from the call. Values 1 to 100100
Cols_ReturnedThe xml tags returned in the result. Options are: sentid, eventid, smstype, numto, data, customerid, status, statusdate. Each entry must be separated by a comma.ChangeID
Date FormatThe 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>
		<customerid></customerid>
		<status></status>
		<statusdate></statusdate>
	</data>
	<call_result>
		<result></result>
		<error/>
	</call_result>
</api_result>
XML tagDescription
changeidA unique ID identifying the change in a message status.
sentidA unique value for each message. You could receive the same SentID back if the message status changes.
eventidWhen sending, an eventid is generated and returned in the result xml. This eventid can be for 1 or “infinity” message entries.
smstypeThis is the type of message sent. (Default = SMS)
numtoThe number the message was sent to.
dataThe data sent to the user.
customeridThe customerid for the message when the data was sent.
statusThe message status. Options are “DELIVRD”, “UNDELIV”, ”UNKNOWN”, ”EXPIRED”.
statusdateThe 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>
ParameterDescriptionDefault
*IDThe max REPLYID from the previous call-
Max_recsThe number of records returned from the call. Values 1 to 100100
Cols_ReturnedThe 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 FormatThe 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>
replyidThe max unique REPLYID for each incoming message
eventidWhen sending an eventid is generated and returned in the result xml. This eventid
can be for 1 or “infinity” message entries.
numfromThe number of the user that sent the incoming message
receiveddataThe data that the user returned
receivedThe date and time the message was received
sentidThe unique sentid for the outgoing message
sentdataThe data sent to the user
sentdatetimeThe date and time the message was sent
sentcustomeridThe customerid for the message when the data was sent
optoutContains the value 1 if the received data matched an opt-out phrase, or 0 if not.

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 tagDescriptionDefault
*start_dateThe start date of the query period. Start_date can be set up to 12 months in the
past.
-
*end_dateThe end date of the query period. The start_date and end_date must be between
1 and 31 days.
-
shortcodesThe collection of short codes. If omitted, will return all short codes assigned to
you with totals for the period.
-
shortcodeA 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 tagDescription
shortcodeYour short code you received messages on.
countThe total count associated to the short code for the period.