Application ID assigned to your application.
Access Token assigned to your application.
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".
The destination number to call. Phone numbers should start with a "+" and country code (E.164 format), e.g. +6511111111.
This is the Caller ID that the destination number will see on their incoming call. Possible values are: your registered number, your Hoiio Number, "private". Numbers should start with a "+" and country code (E.164 format), e.g. +6511111111. If omitted, your registered number will be used as Caller ID.
The maximum duration of the call (in seconds). The time starts when dest picks up the phone.
The number of seconds to ring the destination before considering the Dial as failed. After ring_time has elapsed, and the call hasn't been answered, the call will be ended. If omitted, the destination will be rung until the call is rejected, or the destination number responds with a No Answer tone.
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.
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.
There are 2 ways to start an IVR: receive an incoming call at a Hoiio Number or dial out to a destination number. This API dials out to a destination. For incoming calls, please refer to the Answer block.
With this API, specify the voice message and destination number. A call will be made to the destination. After this step is complete, your application will receive another notification for the next course of action. This API can only be used to start a new IVR session. It cannot be used on an ongoing session.
Hoiio API does not support destination to short code, toll free, premium or emergency numbers.
|status||The result of your request. Refer to Result Status for details.|
|session||A unique session ID for this particular call. Include this
|txn_ref||A unique reference ID for this call transaction. This parameter will not be present if the request was not successful.|
|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_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
|error_msg_invalid_gender||The gender for
|error_msg_invalid_xml||The XML syntax for msg parameter is invalid.|
|error_invalid_notify_url||Invalid URL in
|error_unable_to_resolve_notify_url||Cannot resolve URL in
|error_unable_to_complete_ssl_handshake_notify_url||Cannot complete SSL Handshake with the provided URL in
|error_dest_not_supported||Calling 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_insufficient_credit||You have insufficient credit in your developer account to make this call.|
|error_concurrent_call_limit_reached||You have exceeded the maximum number of concurrent calls. Each account is allowed only 8 active calls at any point of time.|
|error_call_service_not_available||There are problems initiating your call request. Please try again in a few minutes.|
|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
Dial block has finished executing with the following parameters:
|ivr_block||This is an identifer for the type of block this notification is for. You can use this to differenciate between notifications. This block notification can be identified by the value dial.|
|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.|
|dest||The destination number that was called. Phone numbers start with a "+" and country code (E.164 format), e.g. +6511111111.|
|tag||Your own reference ID submitted in the initial Dial requests.|
|call_state||The current state of this call. Possible values are:
|dial_status||Dial status of for the call to dest. Possible values are:
|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. This is present only if call_state=ended.|
|currency||Currency used for this transaction. Refer to Currency Code for the list of currency code. This is present only if call_state=ended.|
|rate||Per-minute charges (sum of both incoming and outgoing call rates) for this call transaction. This is present only if call_state=ended.|
|debit||Total amount billed for this transaction. This is present only if call_state=ended.|
Maximum of 8 active call per application at any point of time
You will be charged the outgoing call rate depending on the country of the destination number.
If you use the Transfer block later on in this call, an additional outgoing call rate (depending on the destination number of the transfer) will be charged. For details of the incoming and outgoing call rate, please refer to the Pricing Section.