Call Conference

Definition

https://secure.hoiio.com/open/conference/call

Parameters

app_id*	string Application ID assigned to your application.
access_token*	string Access Token assigned to your application.
dest*	string A comma-seperated list of destination numbers in E.164 format (start with a "+" and country code) to be called and placed in the conference room. A maximum of 8 numbers are allowed. E.g. +6511111111,+6522222222,+6533333333
room	string A text string representing the conference room ID. Valid characters are a-z, A-Z, 0-9, period (.) and underscore (_) characters. Max 32 characters. Conference rooms are unique to each application and cannot be accessed by other applications or developers. You can also make multiple API request with the same room ID to place participants in an existing conference room. If omitted, a new conference room will be created and a conference room ID will be generated automatically.
caller_id	string This is the Caller ID that each 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.
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, voice/query_status and voice/get_history for your reference. Max 256 characters.
notify_url	string A fully-qualified HTTP/S callback URL on your web server to be notified when a call ends. Refer to Notification parameters for details.

Result Format

{
  "txn_refs":[
    "AA-C-141147","AA-C-141148","AA-C-141149"
  ],
  "room":"R123",
  "status":"success_ok"  
}

Documentation

The Conference API component of Hoiio API provides developers access to telephony services in more than 200 countries around the world. You will be able to initiate call conferences just by making an API request to our servers.

This API will call a list of destination numbers and place them in a conference call.

Hoiio will call the numbers sequentially and place them in the same call conference room. You can also make seperate additional API requests to add new participants to any existing conference room. Each conference room allows a maximum of 8 active participants.

If you want to support inbound conference, refer to IVR Transfer API whch can transfer an incoming call to a conference room. This way, your users can call a Hoiio number and be transferred to a conference room.

Response Parameters

status	The result of your request. Refer to Result Status for details.
txn_refs	An array of unique reference ID for the call transactions. Transaction reference ID are in the same order of the destination numbers provided. This parameter will not be present if the request was not successful.
room	A text string representing the conference room ID. If the room parameter was omitted in the original request, this will be automatically generated for you.

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_tag_invalid_length	`tag` parameter is too long, must be 256 characters or less.
error_dest_invalid	`dest` parameter is invalid.
error_dest_not_supported	Calling to this destination is currently not supported.
error_not_allowed_for_trial	One or more of the destination numbers in dest is not supported for trial accounts. To remove this restriction, please make a credit top-up. See Free Trial for details and supported numbers.
error_invalid_room	`room` parameter is invalid.
error_invalid_notify_url	Invalid URL in `notify_url` parameter.
error_unable_to_resolve_notify_url	Cannot resolve URL in `notify_url` parameter.
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_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

To check on the status of each participant’s call in the conference, you can include the notify_url parameter. If the notify_url parameter was included in your original API request, a notification will be sent to the URL you specified whenever one of the conference participant’s call has ended with the following parameters:

Notification Parameters

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_status_dest	Dial status for the call to the destination number. Possible values are:: answered unanswered failed busy
txn_ref	The unique reference ID for this transaction.
tag	Your own reference ID submitted in the initial [conference/call](doc:call-conference) request. This parameter will not be present if it wasn't included in the initial request.
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 calls per application at any point of time

#Charges

Outgoing call charges apply for calls successfully connected via this API. Calls are charged based on destination and in per-minute blocks. Billing starts when the destination answers the call. Calls to each participant in the conference are charged seperately depending on their call duration.

Please check the Pricing Section for detail charges or you may retrieve the rates with voice/get_rate API.