Definition
https://secure.hoiio.com/open/sms/bulk_send
Parameters
| app_id* | string Application ID assigned to your application. |
| access_token* | string Access Token assigned to your application. |
| dest | string string 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. |
| recipients | string The list of recipient numbers and their associated arguments for the template, as a JSON array, up to a maximum of 1000 numbers. Each entry is a JSON object containing a compulsory dest key.Phone numbers should start with a "+" and country code (E.164 format.) Example: { "recipients": [{ "dest": "+6511111111", "name": "Nick", "age": "22" }, { "dest": "+6522222222", "name": "Dave", "age": "18" }]} (Either this or dest must be present.) |
| sender_name | string 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 | string Contents of the SMS message. It can be a plain message or a Mustache template (Mustache manual.) Example: { "msg": "Hello world!"} { "msg": "Hello , you are years old!"} |
| tag | string This is a text string containing your own reference ID for this transaction. This value will be included in the response for sms/query_status and sms/get_history for your reference. Max 256 characters. |
Result Format
{"bulk_txn_ref":"AA-B-147","status":"success_ok"}
Documentation
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).
Hoiio API does not support destination to short code, toll free, premium or emergency numbers.
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_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_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. |
Limitations
Some Mobile Carriers do not support SMS Delivery Reports (for instance, the majority of US Carriers). For these instances, 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 the status is not updated.
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.