Hoiio Open API logo Hoiio Open API

Definition

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

Parameters

app_id* string
Application ID assigned to your application.
access_token* string
Access Token assigned to your application.
dest1 string
The first number to call. Phone numbers should start with a "+" and country code (E.164 format), e.g. +6511111111. This cannot be the same as dest2 parameter. If omitted, the call will be made to the number registered in your developer account.
dest2* string
The second number to call. Phone numbers should start with a "+" and country code (E.164 format), e.g. +6511111111. This cannot be the same as dest1 parameter.
caller_id string
This is the Caller ID that dest2 will see on their incoming call. The Caller ID for dest1 will always be dest2's number. 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.
max_duration string
The maximum duration of the call (in seconds). The time starts when dest2 picks up the phone.
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 the call ends. The length of this parameter must not exceed 4000 characters. Refer to Notification parameters for details.

Result Format

{"txn_ref":"AA-S-141147","status":"success_ok"}

Response Parameters

status The result of your request. Refer to Result Status for details.
txn_ref A unique reference ID for this call transaction. This parameter will not be present if the request was not successful.

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_dest1_invalid dest1 parameter is invalid.
error_dest2_invalid dest2 parameter is invalid.
error_dest1_not_supported The number to dest1 is not supported by Hoiio.
error_dest2_not_supported The number to dest2 is not supported by Hoiio.
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_same_dest1_dest2 dest1 parameter and dest2 parameter are the same. Calls cannot be make to and from the same number.
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 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_call_service_not_available There are problems initiating your call request. Please try again in a few minutes.
error_internal_server_error There is an unexpected error. Please contact Hoiio support for assistance.

Notifications

To check on the status of the call, 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 when the call has ended with the following parameters:

Notification Parameters

dest1 The first number that was called. Phone numbers start with a "+" and country code (E.164 format), e.g. +6511111111.
dest2 The seconds number that was called. Phone numbers start with a "+" and country code (E.164 format), e.g. +6511111111.
call_status_dest1 Dial status of for the call to dest1. Possible values are:
  • answered
  • unanswered
  • failed
  • busy
call_status_dest2 Dial status of for the call to dest2. 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 voice/call 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.
duration Duration of the call in minutes.
currency Currency used for this transaction. Refer to Currency Code for the list of currency code.
rate Per-minute charges for this call transaction.
debit Total amount billed for this transaction.

API Limits

If you require more than 8 concurrent calls, refer to this.

Charges

Charges apply for calls successfully connected via this API. Calls are charged based on destination and in per-minute blocks. Billing starts when both destination answers the call.

Separate charges apply for connecting the first and second destination number. For example, if you make a call request between Singapore (US$0.015/min*) and USA (US$0.014/min*), you would be billed a total of US$0.029/min* for the call. Please check the Pricing Section for detail charges or you may retrieve the rates with voice/get_rate API.

** Rate accurate as of 17 Jan 2012.*