Web Services API (Legacy)

📘

Important: API Channel Activation for New Accounts and Sub-Accounts

When you create a new Account or Sub-Account, please be aware that by default, no API channels will be active. To enable API access and manage your Accounts and Sub-Accounts' API credentials and settings, please follow the steps outlined in the "API Keys" page.

Note for Accounts Created Before 6 June 2023: If you have an Account that was created before 6 June 2023, the API channels would have been automatically enabled. However, if you wish to switch to an alternative API or use additional APIs, you will need to create an API Key for the desired API.

Overview

The web service can be referenced at https://legacy.mymobileapi.com/api5/api.asmx
The naming convention describes what the function accepts and returns. E.g.: Reply_STR_DS will accept an XML string and return a data set (.net object).
Most of the functions follow a common thread: accept 3 parameters, return XML or dataset.
The returned data will always contain the following:

</api_result>
	<call_result>
		<result>True</result>
		<error/>
	</call_result>
</api_result>

The result will be either “True” or “False”.
If “False” the error will be displayed with the “error” tag.

Sending Messages (Web Services)

To send is relatively easy, but due to the various options it can seem confusing.
In a nutshell:
If you specify a default then it will only be utilised if the entry data does not exist. If neither exists then it will throw an error.
There are 5 methods for sending your messages:

1. Send_DS_DS (Accepts data set, returns data set)
2. Send_STR_DS (Accepts XML string, returns data set)
3. Send_STR_STR (Accepts XML string, returns XML string)
4. Send_DS_STR (Accepts data set, returns XML string)
5. Send _ZIP_ZIP (Accepts zipped stream, returns zipped stream)

Each function accepts 3 parameters

• Username (string)
• Password (string)
• XML string or data set or compressed byte array (depending on the function you choose).

The XML objects looks like this:

<senddata>
	<settings>
		<live>True</live>
		<return_credits>True</return_credits>
		<return_msgs_credits_used>True</return_msgs_credits_used>
		<return_msgs_success_count>True</return_msgs_success_count>
		<return_msgs_failed_count>True</return_msgs_failed_count>
		<return_entries_success_status>True</return_entries_success_status>
		<return_entries_failed_status>True</return_entries_failed_status>
		<default_senderid/>
		<default_date>01/Jan/2018</default_date>
		<default_time>11:15</default_time>
		<default_curdate>01/Jan/2018</default_curdate>
		<default_curtime>11:15</default_curtime>
		<default_data1>This is a default msg</default_data1>
		<default_type>SMS</default_type>
		<default_costcentre>NA</default_costcentre>
		<default_validityperiod>0</default_validityperiod>
	</settings>
	<entries>
		<numto>082*******</numto>
		<customerid>UnqiueValue1</customerid>
		<senderid>Test me</senderid>
		<time>11:15</time>
		<data1>This is a test message 1!</data1>
		<type>SMS</type>
		<costcentre>NA</costcentre>
		<validityperiod>0</validityperiod>
	</entries>
</senddata>

XML Tag Table

The following table determines how the result is formatted, as well as defining the defaults.

🚧

All tags marked with * are mandatory

🚧

Post Paid Customers

Return Credits will always return a value of 1000000 on Post Paid accounts as no credit deduction occurs on this account type.

The output of the following will be defined by the input of the above parameters:

<api_result>
	<entries_failed>
		<numto/>
		<customerid/>
		<reason>numto invalid</reason>
	</entries_failed>
	<entries_success>
		<numto>2782*******</numto>
		<customerid>UnqiueValue1</customerid>
	</entries_success>
	<entries_success>
		<numto>2782*******</numto>
		<customerid>UnqiueValue1</customerid>
	</entries_success>
	<entries_success>
		<numto>27832297941</numto>
		<customerid>d47e1efd‐5e4f‐4832‐ba7f‐07f35d8c10f9</customerid>
	</entries_success>
	<send_info>
		<eventid>27105067</eventid>
		<credits>39763</credits>
		<msgs_credits_used>3</msgs_credits_used>
		<msgs_success>3</msgs_success>
		<msgs_failed>1</msgs_failed>
	</send_info>
	<call_result>
		<result>True</result>
		<error/>
	</call_result>
</api_result>

The following table determines how the result is formatted, as well as defining the defaults.

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>

🚧

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>

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>

🚧

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>

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>Dd/MMM/yyyy HH:mm:ss</date_format>
		<shortcode>unique5digitnumber</shortcode>
		<keyword></keyword>
		<cols_returned>changeid,shortcode,keyword,phonenumber,message,received,mnc,mcc</cols_returned>
	</settings>
</options>

🚧

All entries marked with * are mandatory

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

<api_result>
	<data>
		<changeid>100</changeid>
		<shortcode>unique5digitnumber</shortcode>
		<keyword></keyword>
		<phonenumber>2783*******</phonenumber>
		<message>Testing</message>
		<received>19/Jan/2024 13:40:58</received>
		<mnc>01</mnc>
		<mcc>655</mcc>
	</data>
	<call_result>
		<result>True</result>
		<error/>
	</call_result>
</api_result>

Please see the list of available code examples below:

C# Example

Vb.Net Example

Delphi Example

Check Balance (Web Services)

There are 2 methods for checking your credits:

1. Credits_STR (Returns XML string)
2. Credits_DS (Returns data set)

Each function accepts 2 parameters:

• Username (string)
• Password (string)

The return object looks like this:

<api_result>
	<data>
		<credits>xxxxx</credits>
	</data>
	<call_result>
		<result>True</result>
		<error />
	</call_result>
</api_result>

Your current credit value will be displayed between the “credits” tag.

🚧

Post Paid Customers

Credits will always return a value of 1000000 on Post Paid accounts as no credit deduction occurs on this account type.