Definition
https://secure.hoiio.com/open/ivr/middle/gather
Parameters
| 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. |
| 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". |
| max_digits | string The maximum number of digits to gather. Once the user has input the maximum number of digits, the input will end. Users can also press # to end the input at any time. Valid values are 0-255. Default value is 0 which means users have to press # or wait for timeout to finish inputting. |
| timeout | string The time (in seconds) that the user has to input his response. When timeout is reached, whatever the user has inputted up to that point will be the user's response. Users can also press # to complete the input before timeout is reached. If the user has not input anything when timeout is reach and attempts is 2 or more, the voice message will be replayed and the user has another chance to respond. Valid values are 1 - 300. Default value is 15. |
| attempts | string The number of attempts that the user has to input his response. If the user has not input anything when timeout is reach and attempts is 2 or more, the voice message will be replayed and the user has another chance to response. Valid values are 1 - 255. Default is 1 (i.e. no retries). |
| 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
{"status":"success_ok"}
Documentation
You can get user input via the telephone’s keypad in IVR calls. When users press the keys on the telephone, the numbers are sent to our servers in DTMF format.
Using the Gather block, you can play a voice message to the user, followed by gathering what the user keyed in. The user’s input will then be sent to your application in the notification.
The Gather block will first play the message, wait for the user to response then send a notification to your notify_url. You cannot use this block after you have used any of the End blocks (Transfer, Hangup).
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_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_invalid_max_digits | max_digits parameter is invalid. |
| error_invalid_timeout | timeout parameter is invalid. |
| error_invalid_attempts | attempts parameter is invalid. |
| 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. |
Notifications
You will receive a notification to your application URL when the Gather block has finished executing with the following parameters:
Notification 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 gather. |
| 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:
|
| digits | The user's response. This parameter may be empty if the user did not input anything before the timeout and attempts is reached. |
| 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.. |
API Limits
None
Charges
The prevailing incoming or outgoing call rate applies. See Charges for Answer and Dial block for details.
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.