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 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:
HTTP-Method = "POST" URI-Fragment = "/uapi/phoneCalls/" User-Id "/simple" Query-Parameters = multiple Request-Payload = PhoneCall Return-Object = Array<PhoneCall>
POST /uapi/phoneCalls/@me/simple HTTP/1.1
HOST uapi.voipnow.com
Content Type: application/json
Authorization: Bearer token
{
"extension":"210",
"phoneCallView":[
{
"source":["5354353", "5302040"],
"destination":["5353535"],
"callerId":"John Doe <4242425>"
}
]
}
Request
This section describes how to format the request to the service.
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. |
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 |
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. |
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.
This example creates a PhoneCall between two public phone numbers. The request is made by an App on behalf of a User.
POST /uapi/phoneCalls/@me/simple HTTP/1.1
HOST uapi.voipnow.com
Content Type: application/json
Authorization: Bearer token
{
"extension":"210",
"phoneCallView":[
{
"source":["5354353", "5302040"],
"destination":["3235742879"],
"callerId":"John Doe <4242425>"
}
]
}
Assuming that the request has been successful, the Service sends the following answer:
HTTP/1.1 202 Accepted
...
[
{
"id":"c3e92a04ff422a7a0b9f"
"extension":"210"
"link":
{
"self": "https://x.x.x.x/uapi/phoneCalls/@me/210/c3e92a04ff422a7a0b9f"
}
}
]
Process Overview
STEP 1: The Service identifies the Extension given in the Request-Payload.
STEP 2: Then checks if the number corresponds to a Phone Terminal Extension.
STEP 3: The User of the Extension in question is charged for the PhoneCall.
STEP 4: The Service creates a PhoneCall resource also owned by this User.
STEP 5: The Service calls the source phone numbers given in the Request-Payload (e.g. 5354353 and 5302040). As soon as one picks up, the calls to the other phone numbers are dropped.
STEP 6: If a callerId is given in the Request Payload, it is displayed to the numbers used as the source, when they receive the call.
The callerId must suit the UAPI-Caller-Id data type. If not sent in the request, the Service uses the one set on the extension given in the Request-Payload.
STEP 7: Once the Service connects to the source, it calls the destination number given in the Request-Payload.
When the request is made using an App registered to the Administrator account or to an Organization, the userId cannot be set to @me and must be specified.
This example creates a PhoneCall between two phone numbers. The request is made by an App on behalf of a User.
POST /uapi/phoneCalls/12/simple HTTP/1.1
HOST uapi.voipnow.com
Content Type: application/json
Authorization: Bearer token
{
"extension": "0003*210",
"phoneCallView": [
{
"source": [ "5354353", "5302040" ],
"destination": [ "3235742879" ],
"callerId": "John Doe <4242425>"
}
]
}
Assuming the request has been successful, the Service returns the following answer:
HTTP/1.1 202 Accepted
...
[
{
"id" : "c3e92a04ff422a7a0b9f"
"extension": "0003*210"
"link":
{
"self": "http://x.x.x.x/uapi/phoneCalls/@me/0003*210/c3e92a04ff422a7a0b9f"
}
}
]
Process Overview
The same process as the one for the App registered to the User account occurs.
This example connects an extension to the system using the SandBox numbers. The request is made by an App on behalf of a User.
POST /uapi/phoneCalls/12/simple HTTP/1.1
HOST uapi.voipnow.com
Content Type: application/json
Authorization: Bearer token
{
"extension": "0003*210",
"phoneCallView": [
{
"source": [ "0003*210" ],
"destination": [ "0003*00" ],
"callerId": "John Doe <4242425>"
}
]
}
Assuming the request has been successful, the Service returns the following answer:
HTTP/1.1 202 Accepted
...
[
{
"id" : "c3e92a04ff422a7a0b9f"
"extension": "0003*210"
"link":
{
"self": "http://x.x.x.x/uapi/phoneCalls/@me/0003*210/c3e92a04ff422a7a0b9f"
}
}
]
Except where otherwise noted, content in this space is licensed under a Creative Commons Attribution 4.0 International.