Transfer

Definition

https://secure.hoiio.com/open/ivr/end/transfer

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".
dest*	string The destination to transfer the call to. This can be either a E.164 format destination number (start with a "+" and country code, e.g. +6511111111) or a conference room ID. To transfer to a conference room, use the room: URI schema followed by the room ID (e.g. dest=room:R1234). To create a new conference room, use an empty room ID (e.g. dest=room:).
caller_id	string 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.
on_failure	string Action to perform if the transfer fails. You can choose either: hangup: the IVR session will be hung up. Call state is ended. continue: the IVR session will continue. You can issue another Middle or End block. Call state is ongoing If omited, action hangup will be used by default.
ring_time	string 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.
room_profile	string When transferring to a conference room, you can the configure sound that is continuously played in the room when there is only one person. There are two allowed values for this parameter: music: music will be played, default if parameter is omitted. ringing: ringing sound will be played.
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

{"txn_ref":"AA-S-141147","session":"S4643"}

Documentation

The Transfer block allows you to transfer the current call to another destination number anywhere in the world or a voice conference room. Your user will continue to hold on the line while the call is being transferred. It is recommended that you play a voice message informing the user before you transfer the call.

The Transfer block will first play the message then transfer the call. If the transfer failed, you can follow up with one of the Middle or End blocks. If the transfer succeeds, you will get a notification after the transferred call has ended.

Response Parameters

status	The result of your request. Refer to Result Status for details.
room	A text string representing the conference room ID when transferring the call to a conference room. If the room ID was omitted in the original request, this will be automatically generated for you. This parameter will not be available when transferring the call to a E.164 number.

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_dest_invalid	`dest` parameter is invalid.
error_dest_not_supported	Calling to this destination is currently not supported.
error_caller_id_invalid	`caller_id` parameter is invalid.
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_number_not_supported	Destination number is not supported or 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 Transfer block has finished executing (after the call has ended or the transfer has failed) 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 transfer.
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: ongoing - This call has been answered. You should follow up with one of the Middle or End blocks. 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. 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

Maximum of 8 active participants in each conference room
Maximum of 8 active call per application at any point of time

Charges

The prevailing incoming or outgoing call rate applies. See Charges for Answer and Dial block for details.

For transferring to a conference room, there are no additional charges

For transferring to a destination number, 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.