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:
- Send_DS_DS (Accepts data set, returns data set)
- Send_STR_DS (Accepts XML string, returns data set)
- Send_STR_STR (Accepts XML string, returns XML string)
- Send_DS_STR (Accepts data set, returns XML string)
- 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.
live | If Live = false then it will return the result but won’t send the data. It won’t appear in your sent report. | True |
return_credits | If True then the current credits count will be returned. | False |
return_msgs_credits_used | If True then the amount of credits used will be returned | False |
return_msgs_success_count | If True then the total success data count will appear in the result. | False |
| If True then the total failed data count will appear in the result. | False |
return_entries_success_status | If True then the data that is accepted will be returned in the result. | False |
return_entries_failed_status | If True then the data that is rejected will be returned in the result. | False |
default_senderid | This is the default setting for the call but can be overridden by the individual entries. Only certain accounts can alter this. | Repliable |
*default_date | This is the date the messages must be sent out. | |
*default_time | This is the time the messages must be sent out. | |
default_curdate | This is the current date on your server. It is used to determine when your messages should go out. If not used then the server date is used. | Sever Date |
default_curtime | This is the current time on your server. It is used to determine when your messages should go out. If not used then the server time is used. | Server Time |
default_data1 | This is the default setting for the call but can be overridden by the individual entries. | |
default_type | This is the default setting for the call. | SMS |
default_costcentre | Will be used in future. | "" |
mo_forwardemail | All incoming replies will be forwarded to this email address | "" |
default_validityperiod | This is the amount of time, in hours, that an SMS should remain valid. The network will continue to try to deliver the SMS for the amount of time specified. |
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.
All tags marked with * are mandatory
XML tag | Description |
|---|---|
entries_failed | If this tag exists then some of the data you pushed has errors.
|
entries_success | If this tag exists then it will contain “numto” and “customerid”. |
send_info | This describes the overall data returned. It WILL contain “eventid” and COULD have “credits”, “msgs_credits_used”, “msgs_success” and “msgs_failed”.
|
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.
XML tag | Description | Default |
|---|---|---|
live | If Live = false then it will return the result but won’t send the data. It won’t appear in your sent report. | True |
return_msgs_credits_used | If True then the amount of credits used will be returned. | False |
return_credits | If True then the current Credits count will be returned. | False |
return_msgs_success_count | If True then the total success data count will appear in the result. | False |
return_entries_failed_status | If True then the total failed data count will appear in the result. | False |
return_entries_success_status | If True then the data that is accepted will be returned in the result. | False |
return_entries_failed_status | This is the default setting for the call but can be overridden by the individual entries. Only certain accounts can alter this. | False |
*default_date | This is the date the messages must be sent out. | |
*default_time | This is the time the messages must be sent out. | |
default_curdate | This is the current time on your server. It is used to determine when your messages should go out. If not used then the server time is used. | Server Date |
default_curtime | This is the current time on your server. It is used to determine when your messages should go out. If not used then the server time is used. | Server Time |
default_data1 | This is the default setting for the call but can be overridden by the individual entries. | "" |
default_type | This is the default setting for the call. | SMS |
default_costcentre | "" | |
mo_forwardemail | All incoming replies will be forwarded to this email | "" |
default_validityperiod | The amount of time in hours an SMS should remain valid. The network will continue to try to deliver the SMS over the validity period. |
All entries marked with * are mandatory
Updated 20 days ago