SMS API - Send SMS
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).
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 rebrand your SMS to your company name or any text that you want. For example, you may change the sender name of your SMS to "Hoiio" and your SMS recipient will see this as the sender of the SMS (instead of the usual phone number). This would be useful in marketing and branding your company or application to your users.
We do not support SMS rebranding to
China,
Dijibouti,
Indonesia (XL, Matrix, IM3),
Malaysia,
South Africa,
and
Vietnam (Viettel).
For messages to these destinations, we will append
Fr:<sender_name>\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 ommitted or set to something that is
not your US Hoiio Number, we will append Fr:<sender_name>\n
to the start of your message.
Sender Names must be:
- 3-11 characters (alphanumeric) or 3-15 characters (numeric) AND
- only A-Z, a-z, 0-9 and the plus (+) characters are allowed
This feature is disabled for developers by default. To enable this feature, please click on "SMS Rebranding" in your Developer Portal.
API URL:
https://secure.hoiio.com/open/sms/send
| Request Parameters |
| app_id |
Required |
Application ID assigned to your application. |
| access_token |
Required |
Access Token assigned to your application. |
| dest |
Required |
The recipient number of the SMS. Phone numbers should start with a "+" and country code (E.164 format), e.g. +6511111111. |
| 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 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 Notification parameters for details. |
| Response Parameters |
| status |
The result of your request. Refer to Result Status for details. |
| txn_ref |
A unique reference ID for this SMS transaction. This parameter will not be present if the request was not successful. |
| Result Status |
| success_ok |
The request has been processed successfully and the SMS has been queued for sending. |
| 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_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_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:
{"txn_ref":"AA-S-141147","status":"success_ok"}
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:
| 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.
- 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 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.
|
