IVR API - Monitor

The Monitor block allows you to record the call conversation, including any voice messages. The recording of the monitored call are then made available to you in MP3 format for download after the call has ended. The download URL for the recording will be sent to your application in the notification.

It is recommended that you play a voice message informing the user before you start monitoring. You cannot use this block after you have used any of the End blocks (Transfer, Hangup).

API URL:

https://secure.hoiio.com/open/ivr/middle/monitor

Request Parameters
app_id	Required	Application ID assigned to your application.
access_token	Required	Access Token assigned to your application.
session	Required	The unique session ID for this particular call.
msg	Optional	This is the message that you want to play to inform the user before the start of the recording. Max 500 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 langauge 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 another 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>http://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	Optional	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	Required	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.

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_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_monitor_in_progress	This call is already being monitored.
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:

{"status":"success_ok"}

Notifications

After the session has ended, you will receive a notification to your application URL with the following parameters:

Notification Parameters
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.
tag	Your own reference ID submitted in the initial request.
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.
monitor_url	You can download the recording in MP3 format from this URL. An example of the URL is: https://hoiio.s3.amazonaws.com/recordings/rec-100.mp3?Expires=1640069813 &AWSAccessKeyId=AKIAJR6MXIPT57P5JSDQ&Signature=V32sDkOZ4hXJb%2Ffh3BFSiy%2Bkg%2F0%3D

API Limits

None

Charges

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