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, 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>
<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. |
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. |
Updated 5 months ago