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_data2/>
        <default_flash>False</default_flash>
        <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>
        <data2/>
        <flash>False</flash>
        <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

returnentries
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

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.
Format is dd/MMM/yyyy eg: 13/apr/2009

*default_time

This is the time the messages must be sent out.
Format is HH:mm eg: 17:34

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_data2

This is the default setting for the call but can be overridden by the individual entries.

default_flash

This is the default setting for the call but can be overridden by the individual entries.

False

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.
If will contain: “numto”, “customerid” and “reason”. The reason will be

  • numto invalid
  • senderid invalid
  • time invalid
  • flash invalid
  • costcentre invalid
  • type invalid
  • data1 invalid
  • data2 invalid
  • data1 + data2 invalid

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”.

  • Credits = credits remaining in account
  • Msgs_credits_used = the amount of credits used
  • Msgs_success = a count of the messages accepted for delivery
  • Msgs_failed = a count of the messages rejected

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>

You can also send to a group if it exists in your group list online.
Add the send_groupid tag to your XML object.
E.g:

<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_data2/>
        <default_flash>False</default_flash>
        <default_type>SMS</default_type>
        <default_costcentre>NA</default_costcentre>
        <default_validityperiod>0</default_validityperiod>
    <send_groupid>0</send_groupid>
    </settings>

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.
Format is dd/MMM/yyyy eg: 13/apr/2009

*default_time

This is the time the messages must be sent out.
Format is HH:mm eg: 17:34

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_data2

This is the default setting for the call but can be overridden by the individual entries.

""

default_flash

This is the default setting for the call but can be overridden by the individual entries.

False

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.

*groupid

The groupid to send to

0

🚧

All entries marked with * are mandatory