Hoiio Open API




app_id* string
Application ID assigned to your application.
access_token* string
Access Token assigned to your application.
session* string
The unique session ID for this particular call.
force string
This should be set to enabled if the call session should be hung up immediately. With this option, the Hangup Block can be called at any point of the IVR session, even while in the middle of blocks. It should be noted that a message cannot be played when performing a force hangup - the msg parameter should not be provided.
msg string
The message that you want to play after the call is answered. Max 1000 characters. Languages and Gender To change the language or gender, use the <speech> markup. E.g. <speech language="zh-HK" gender="female">請稍等,我們正在處理您的訂單。</speech> Default language is English and default gender is Female. For the list of supported language and gender, please refer to Text-to-Speech for more details. Custom Recordings If you would like to use your own voice recordings or voice messages recorded via the Record block, use the <url> markup to specify a file for us to use. We will download the file and use it as the voice message. E.g. <url>https://example.com/myrecording.mp3</url> Only HTTP and HTTPS URL are supported. Supported file formats are .mp3, .wav and .gsm (8000 Hz, mono channel). File size must be 10MB or less. Note: There might be a slight delay when downloading the file for the first time. To enable us to cache your file locally for subsequent calls, please include the "Last-Modified" HTTP header. Subsequent calls will not have the delay if we are able to cache your file. If you have updated your file, make sure your file hosting web server respond to our HTTP header "If-Modified-Since" in our request with a "304 Not Modified".
tag string
This is a text string containing your own reference ID for this transaction. This value will be included in the response for Notification for your reference. Max 256 characters.
notify_url string
A fully-qualified HTTP/S URL on your web server to be notified when this action has completed execution. The length of this parameter must not exceed 4000 characters. See Controlling IVR Behavior for more details. If omitted, the call will hang up after msg is played, and the notification will not be sent to you.

Result Format



To hang up the current call, you can use the Hangup block. Upon receiving this action, the current call will be hang up.

The Hangup block will first play the message, hang up the call then send a notification to your notify_url. You cannot use any other block after using the Hangup block.

Tip: Using the force parameter, you can call this API at any point of time when a call is in progress to hang up the call. You do not need to wait for a notification before calling this API. However, if ivr/hangup is used in this way, the msg parameter cannot be used.

Response Parameters

status The result of your request. Refer to Result Status for details.

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_msg_invalid_length Your msg parameter is too long, must be 500 characters or less.
error_msg_cannot_convert_text There was an error converting msg parameter to speech. Make sure you have selected the correct langauge.
error_msg_download_failed There was an error downloading the custom speech file from your URL.
error_msg_invalid_file_format The custom speech file format is not supported or it has the wrong filename extension. Only .mp3, .wav and .gsm files are supported.
error_msg_invalid_file_size The custom speech file size must be 10MB or less.
error_msg_invalid_url The URL for the custom speech file is invalid.
error_msg_invalid_language The language for msg parameter is not supported. For the list of supported languages, please refer to Text-to-Speech for more details.
error_msg_invalid_gender The gender for msg parameter is not supported. For the list of supported genders, please refer to Text-to-Speech for more details.
error_msg_invalid_xml The XML syntax for msg parameter is invalid.
error_tag_invalid_length tag parameter is too long, must be 256 characters or less.
error_invalid_notify_url Invalid URL in notify_url parameter.
error_unable_to_resolve_notify_url Cannot resolve URL in notify_url parameter.
error_unable_to_complete_ssl_handshake_notify_url Cannot complete SSL Handshake with the provided URL in notify_url parameter. Check if your cert chain is complete using an SSL checker.
error_invalid_session The session is invalid.
error_session_access_denied You do not have access to this session.
error_hangup_already_in_progress You have already issued the Hangup block for this session. Call teardown is in progress, please wait for the notification to arrive.
error_cannot_play_msg_with_force You have provided a msg parameter along with the force parameter - messages cannot be played when a hangup is forced.
error_session_ended The session is ended or expired.
error_session_not_ready The session is not ready for a this request as we are still processing your previous request. You should only send another request when you receive the post notification at the notify_url for the previous request.
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.


You will receive a notification to your application URL when the Hangup block has finished executing with the following parameters:

Notification Parameters

ivr_block This is an identifier for the type of block this notification is for. You can use this to differentiate between notifications. This block notification can be identified by the value hangup.
session This is a unique session ID for this particular call. Include this session in your subsequent requests to select what action to take next.
txn_ref The unique reference ID for this transaction.
from The incoming Caller ID of this call. Phone numbers start with a "+" and country code (E.164 format), e.g. +6511111111. This is present only if the call is an incoming call to a Hoiio Number.
to The dialed number of this call (your Hoiio Number). Phone numbers start with a "+" and country code (E.164 format), e.g. +6511111111. This is present only if the call is an incoming call to a Hoiio Number.
dest The destination number that was called. Phone numbers start with a "+" and country code (E.164 format), e.g. +6511111111. This is present only if the call is an outgoing call made via the Dial block.
call_state The current state of this call. Possible values are:
  • ended - This call has ended. You should not send any more requests for this call.
date Date/time (GMT+8) of this transaction in "YYYY-MM-DD HH:mm:SS" format. This is present only if call_state=ended.
duration Duration of the call in minutes.
currency Currency used for this transaction. Refer to Currency Code for the list of currency code.
rate Per-minute charges (sum of both incoming and outgoing call rates) for this call transaction.
debit Total amount billed for this transaction.

API Limits



Call charges will stop when you use the Hangup block. For details of the incoming and outgoing call rate, please refer to the Pricing Section.