SMS API - Send Bulk SMS

This API allows you to send SMS in bulk (up to 1000 messages) to any mobile numbers in more than 200 countries (for the full list of supported destinations, please check the Pricing Section). SMS to land lines are not supported.

API URL:

https://secure.hoiio.com/open/sms/bulk_send
Request Parameters
app_id Required Application ID assigned to your application.
access_token Required Access Token assigned to your application.
dest Required The list of recipient numbers of the SMS, separated by comma, up to a maximum of 1000 numbers. Phone numbers should start with a "+" and country code (E.164 format)
e.g. +6511111111,+6522222222,+6533333333.
sender_name Optional This is the sender name that the recipient of your SMS will see. For more details, refer to Sender Rebranding.

If omitted, your registered number will be used as the sender name.
msg Required Contents of the SMS message.
tag Optional This is a text string containing your own reference ID for this transaction. This value will be included in the response for Delivery Notification, sms/query_status and sms/get_history for your reference. Max 256 characters.
notify_url Optional A fully-qualified HTTP/S callback URL on your web server to be notified when the SMS has been delivered. The length of this parameter must not exceed 4000 characters. Refer to Delivery Notification parameters for details.

Response Parameters
status The result of your request. Refer to Result Status for details.
Note that success status doesn't mean all the messages are sent. The status of each of the message will be returned to you in the Transaction Notification.
bulk_txn_ref A unique reference ID for this Bulk SMS transaction. This parameter is returned to you in the Transaction Notification. This parameter will not be present if the request was not successful.

Result Status
success_ok The request has been processed successfully.
error_invalid_http_method Invalid HTTP method. Only GET or POST are allowed.
error_malformed_params HTTP POST request parameters contains non-readable bytes.
error_X_param_missing A required parameter is missing. X is the name of the parameter that is missing.
error_invalid_access_token Your Access Token is invalid, expired or has been revoked.
error_invalid_app_id Your Application ID is invalid or has been revoked.
error_tag_invalid_length tag parameter is too long, must be 256 characters or less.
error_not_allowed_for_trial Only your registered mobile number can be the destination number(s) for trial accounts. To remove this restriction, please make a credit top-up. See Free Trial for more details.
error_msg_empty msg parameter is empty.
error_msg_too_big msg parameter length is too big. Refer to Message character limits above.
error_dest_too_many dest parameter contains too many destinations. We support a maximum of 1000 destinations.
error_no_valid_dests The dest parameter does not contain any valid destinations conforming to the E.164 format. This error can occur if the wrong destination delimiter (any character that is not the comma ",") is used.
error_sms_rebrand_not_enabled SMS Rebranding is not enabled for your application. Please enable it in your Developer Portal.
error_invalid_sender_name sender_name parameter is invalid.
error_invalid_notify_url Invalid URL in notify_url parameter.
error_unable_to_resolve_notify_url Cannot resolve URL in notify_url parameter.
error_insufficient_credit You have insufficient credit in your developer account to send this SMS.
error_rate_limit_exceeded You have exceeded your request limit for this API. Refer to API Limits for details.
error_internal_server_error There is an unexpected error. Please contact Hoiio support for assistance.

Sample Response:

{"bulk_txn_ref":"AA-B-147","status":"success_ok"}

Transaction Notifications

The transaction references of all the SMSes will be sent to you if you include the notify_url parameter. A notification will be sent to the this URL for each of the sms when we send them. If you have 100 numbers in your dest request paramenter, you will receive 100 transaction notifications.
The notification will include the following parameters:

Transaction Notification Parameters
status Status of the SMS transaction. Possible values are:
  • success_ok: The SMS has been successfully queued for sending.
  • error_dest_invalid: dest parameter is invalid.
  • error_dest_not_supported: SMS to this destination is currently not supported.
txn_ref The unique reference ID for this transaction. This parameter will only be present if the request status is success_ok.
dest The destination of this particular SMS. This parameter will only be present if the request status is success_ok.
bulk_txn_ref The unique reference ID of the bulk transaction. This parameter is returned to you in the response. This parameter will only be present if the request status is success_ok.

Delivery Notifications

To check on the delivery status of the SMS, you can include the notify_url parameter. If the notify_url parameter was included in your original API request, a notification will be sent to the URL you specified when there is an update in status for your SMS delivery.

The notification will include the following parameters:

Delivery Notification Parameters
sms_status Status of the SMS delivery. Possible values are:
  • delivered: The SMS has been delivered to the recipient's telco.
  • failed: The SMS sending has failed./li>
  • error: An internal error has occurred.
txn_ref The unique reference ID for this transaction.
tag Your own reference ID submitted in the initial sms/send request. This parameter will not be present if it wasn't included in the initial request.
date Date/time (GMT+8) of this transaction in "YYYY-MM-DD HH:MM:SS" format.
dest The recipient number of the SMS. Phone numbers start with a "+" and country code (E.164 format), e.g. +6511111111.
split_count The number of multipart SMS that this message has been split into.
currency Currency used for this transaction. Refer to Currency Code for the list of currency code.
rate Per multipart SMS charges for this transaction.
debit Total amount billed for this transaction.

Limitations

Our delivery notifications are dependent on SMS Delivery Reports provided by Mobile Carriers. However, these Delivery Reports are not provided by all Carriers (for instance, the majority of US Carriers). In these instances, we will not be able to provide notifications. The status of the SMS provided by our sms/get_history and sms/query_status APIs will show the sms status as "queued" for these messages.

If your application is dependent on the confirmation of SMS delivery, we would advise that you test against numbers from each of the different Mobile Carriers that your customers would be using, to determine if all these Carriers support SMS Delivery Reports.

Do note, that SMS Delivery Reports are still a best-effort service, and you should still handle for cases when you do not receive notifications.

API Limits

None.

Charges

Charges apply for each of the SMS that is sent via this API. SMS are charged based on destination and in per multipart SMS. Charges still apply if the SMS was block by the recipient's telco. Please check the Pricing Section for charges or you may retrieve the rate for each SMS with sms/get_rate API.