Excerpt |
---|
This method allows making new PhoneCalls in particular contexts such as User, Organization or global. |
Table of Contents | ||||
---|---|---|---|---|
|
Request/Response model
Overview
Use this request to make phone calls between two parties.
If successful, the request returns the Id of the newly created PhoneCall as well as other useful properties.
The Id can be used later to to query the status of the phone call, hang it up or update it using the available actions.
The request is made by an App that is registered to a User account.
To create phone calls, issue a HTTP POST request:
Panel | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||
HTTP-Method = "POST" URI-Fragment = "/uapi/phoneCalls/" User-Id "/simple" Query-Parameters = multiple Request-Payload = PhoneCall Return-Object = Array<PhoneCall> |
Panel | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||
POST /uapi/phoneCalls/@me/simple HTTP/1.1
HOST |
Request
This section describes how to format the request to the service.
Anchor | ||||
---|---|---|---|---|
|
URI fragment
The following parameters must be sent in the URI fragment:
Name | Type | Required | Description |
---|---|---|---|
userId | Yes | Id of the User on behalf of whom the phone call is made. |
Anchor | ||||
---|---|---|---|---|
|
Query Parameters
All requests to make phone calls support the Standard-Request-Parameters and the custom fields parameter. All parameters are optional.
Name | Type | Required | Description |
---|---|---|---|
waitForPickup | Number | No | The maximum number of seconds to wait until one of the phone numbers used picks up. |
callDuration | Number | No | Total duration of the call, in seconds. |
allowPublicTransfer | Boolean | No | This flag restricts or permits transfer of a phone call made to a phone number external to the system. |
video | Boolean | No | Enable video support in SDP. Default: false |
Anchor | ||||
---|---|---|---|---|
|
Request Payload
When making PhoneCalls, the following restrictions apply to the PhoneCall resource sent in the Request Payload.
Name | Type | Description |
---|---|---|
extension | UAPI-Extension-Number | Must refer to a Phone Terminal type Extension.Must be owned by the User identified by the userId sent in the URI-Fragment.Cannot be set to @self and if missing the first value of the source is used. |
source | Array<String> | Can be set to a list of extension numbers or public numbers. |
destination | Array<String> | Can be any extension number or a public number. |
callerId | UAPI-Caller-Id | The caller name and number. |
callerIdDestination | UAPI-Caller-Id | The caller name and number. It is displayed to the destination. Default: the Caller Id of the Phone Terminal Extension. |
nonce | String | A unique string which allows to identify the call created based on the request. |
Tip |
---|
Short extension numbers can be given as source, extension, and destination, but only when the request is made using an App registered to an User or an Organization. |
Response
Success
If successful, the Service returns the Id of the newly created PhoneCall and the following HTTP statuses:
HTTP Code | Description |
---|---|
200 | The Id of the phone call is returned. |
204 | There is no Id to be returned. |
Failure
When it fails, the request returns the following error codes:
HTTP Code | Code | Description |
---|---|---|
400 | extension_invalid | Value supplied in extension parameter is missing or invalid. The parameter must be set to the number of a Phone Terminal extension that must be owned by the user. Default has the same value as the source parameter. |
400 | pc_duration_invalid | Value supplied in callDuration parameter is missing or invalid. The parameter must be set to a numeric value and represents the mandatory duration of a phone call in seconds. |
400 | pc_source_invalid | Value supplied in source parameter is missing or invalid. The parameter must be set to a list of extended or short extension numbers or public phone numbers. |
400 | pc_destination_invalid | Value supplied in destination parameter is missing or invalid. The parameter must be set to a list of extended or short extension numbers or public phone numbers. |
400 | pc_timeout_invalid | Value supplied in waitForPickup parameter is missing or invalid. The parameter must be numeric and higher than 0. |
400 | pc_callerid_invalid | Value supplied in callerId parameter is missing or invalid. The parameter must be set to a value with the format: John Doe <+3334444>. |
400 | pc_transfer_invalid | Value supplied in allowPublicTransfer parameter is missing or invalid. The parameter must be set to true or false. |
400 | pc_callerid_invalid | You are not allowed to set the callerid field. |
400 | pc_nonce_invalid | Value supplied in nonce parameter is missing or invalid. |
Examples
Below you can find three examples that will help you understand the request and the response.
Localtab Group | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Except where otherwise noted, content in this space is licensed under a Creative Commons Attribution 4.0 International.