Retrieve data from the API (Parameter Based)

OVERVIEW

The SMS Gateway is designed to allow easy retrieval of your sent items and replies.
The design allows the following:

• Retrieval of items you have not already pulled
• Instant retrieval of data (due to API table design and indexing)
• Customisation to the result format
• Prevention of timeouts

1. Sent Items

The API system uses a unique identity field called “changeid” which increments permanently. When a message status is received from the corresponding network, a new record is written to the API and the changeid will increment by 1. Messages will not be retrieved via the API that do not have any status changes.

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 API_Sent_Table where changeid > @ID order by changeid asc”

📘

Tip:

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

RETRIEVING SENT DATA (PARAMETER BASED)

The function accepts the following parameters:

• Type (String) = “sentparam”
• Username (String)
• Password (String)

Example string:
https://legacy.mymobileapi.com/api5/http5.aspx?Type=sentparam&username=xxx&password=yyy&id=zzz

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:

XML

<api_result>
	<data>
		<changeid>21437610891</changeid>
		<sentid>67393185816</sentid>
		<eventid>6403219457</eventid>
		<smstype>Sms</smstype>
		<numto>278********</numto>
		<data>This is a test msg</data>
		<customerid>UnqiueValue1</customerid>
		<status>DELIVRD</status>
		<statusdate>1/Jan/2024 07:53:09</statusdate>
	</data>
	<call_result>
		<result>True</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 a single or bulk SMS, an eventid is generated. This will be 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 mobile number
customerid	The customerid for the message when the data was sent
status	The message status. Options are “DELIVRD”, “UNDELIV”, “BLIST”, “EXPIRED”
statusdate	The date and time the message was sent

2. Replies

The API system uses a unique identity field called “ReplyID” which increments permanently. When an inbound message is received from the corresponding network a new record is written to the API and hence 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 utilized by the next call. The following is occurring with 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).

RETRIEVING REPLIES (PARAMETER BASED)

The function accepts 4 parameters:

• Type (String) = “repliesparam”
• Username (String)
• Password (String)

Example string:
https://legacy.mymobileapi.com/api5/http5.aspx?Type=repliesparam&username=xxx&password=yyy&id=zzz

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, sentid, sentdata, sentcustomerid, received, sentdatetime, optout. Each entry must be separated with 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:

XML

<api_result>
	<data>
		<replyid>509871807</replyid>
		<eventid>>6414283881</eventid>
		<numfrom>278********</numfrom>
		<receiveddata>Reply Received</receiveddata>
		<sentid>67758922377</sentid>
		<sentdata>my test msg reply</sentdata>
		<sentcustomerid/>UnqiueValue1</sentcustomerid>
		<received>19/Jan/2024 13:40:58</received>
		<sentdatetime>19/Jan/2024 13:40:49</sentdatetime>
  	<optout>false</optout>
	</data>
	<call_result>
		<result>True</result>
		<error/>
	</call_result>
</api_result>

XML tag	Description
* ReplyID	The max unique REPLYID for each incoming message
EventID	When sending a single or bulk SMS, an eventid is generated. This will be 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
SentID	The unique sentid for the outgoing message
SentData	The data sent to the user
SentCustomerID	The customerid for the message when the data was sent
Received	The date and time the message was received
SentDateTime	The date and time the message was sent
OptOut	The value will be True if the reply contains an opt-out trigger word, like STOP, OPTOUT or REMOVE

🚧

All entries marked with * are mandatory