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:
|
| call_status_dest2 |
Dial status of for the call to dest2. Possible values are:
|
| 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
- Calls cannot be made from and to the same number
- No more than 8 concurrent calls per account
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.*