Hoiio Open API logo Hoiio Open API

Definition

https://secure.hoiio.com/open/sms/send

Parameters

app_id* string
Application ID assigned to your application.
access_token* string
Access Token assigned to your application.
dest* string
The recipient number of the SMS. Phone numbers should start with a "+" and country code (E.164 format), e.g. +6511111111.
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.
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

{"txn_ref":"AA-S-141147","status":"success_ok"}

Documentation

This API allows you to send SMS to mobile numbers in over 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.

Message Characters Limit

Each SMS are limited to 160 ASCII characters or 70 unicode characters. For messages that are longer, Hoiio will split them into multipart SMS up to a maximum of 3 SMS. Most mobile phones will be able to automatically reassemble these multipart SMS and present to the recipient as a single message.

Message character limits and number of SMS required:

  1 SMS required 2 SMS required 3 SMS required
ASCII 160 characters or less 306 characters or less 459 characters or less
Unicode 70 characters or less 134 characters or less- 201 characters or less

The following ASCII characters counts as 2 characters when determining message length:

\n Line feed
[ Left square bracket
] Right square bracket
\ Backslash
^ Circumflex accent
{ Left curly bracket
} Right curly bracket
| Vertical bar
Euro sign

SMS Rebranding

This feature allows you to change your SMS sender name to your company name or any text that you want.

SMS rebranding has been tested to work in:

For other countries, we will still send your message with the rebranded sender name, but the telco may override it. You may test this quickly with your trial account after you log in to the developer portal.

We do not support SMS rebranding to

For messages to these destinations, we will append \n` to the start of your message. Note that these additional characters count towards your total message length.

For sending SMS to USA, we can only rebrand to your US Hoiio Number. If sender_name is not set to your US Hoiio Number, we will append Fr:<sender_name>\n to the start of your message.

Sender Names must be:

This feature is disabled for developers by default. To enable this feature, please click on “SMS Rebranding” in your Developer Portal.

Response Parameters

status The result of your request. Refer to Result Status for details.
txn_ref The unique reference ID for this transaction.

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_dest_invalid dest parameter is invalid.
error_dest_not_supported SMS to this destination is currently not supported.
error_dest_same_as_sender SMS to the destination must not be the same as your sender number. By default, the sender number is your registered number.
error_not_allowed_for_trial Destination number not supported for trial accounts. To remove this restriction, please make a credit top-up. See Free Trial for details and supported numbers.
error_msg_empty msg parameter is empty.
error_msg_too_big msg parameter length is too big. Refer to Message character limits above.
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). In 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 where the status is not updated.

Charges

Charges apply for SMS that are 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 rates with sms/get_rate API.