Request/Response model
Overview
Use this request to transfer a phone call to Voicemail.
The Service identifies the phone call using the User Id, Extension number and PhoneCall Id.
If successful, the Service returns the PhoneCall that was updated. UnifiedAPI can also transfer the phone call to a third-party number.
The request is made by an App that is registered to a User account.
To transfer a phone call to Voicemail in a desired context, issue a HTTP PUT request:
HTTP-Method = "PUT"
URI-Fragment = "/uapi/phoneCalls/" User-Id "/" Extension-Number "/" PhoneCall-Id
Query-Parameters = null
Request-Payload = PhoneCallAction
Return-Object = PhoneCall
GET /uapi/phoneCalls/12/0003*210/b817d2618fe6f1804db1 HTTP/1.1 HOST uapi.voipnow.com Content Type: application/json Authorization: Bearer token
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 that owns the Extension involved in the call. | |
extension | Yes | Number of the Extension involved in the call. | |
phoneCallId | Yes | Specifies the Id of a PhoneCall resource that must be updated, otherwise all PhoneCall resources of the extension will be updated. |
Request Payload
When transferring a PhoneCall to Voicemail, the following restrictions apply to the PhoneCall resource sent in the Request Payload:
| Name | Type | Required | Description |
|---|---|---|---|
| action | String | Yes | Action must be set to TransferToVoicemail. |
| sendCallTo | UAPI-Extension-Number | Yes | Number of the Extension where the phone call should be transferred. Must be in the same Organization as the Extension given in the URI-Fragment and must be multi-user aware. Must refer to a Phone Terminal type Extension. |
| transferFromNumber | UAPI-Extension-Number | No | The phone number of the party that transfers the call. Its value can be the phone number of the source or destination. If missing the value from sendCallTo will be used. |
| transferNumber | UAPI-Extension-Number | Yes | The phone number of the party being transferred. Its value can be the phone number of the source or destination. |
Response
Success
If successful, the Service returns the PhoneCall that was updated and the following HTTP statuses:
| HTTP Code | Description |
|---|---|
| 200 | The phone call is transferred. |
| 204 | There are no phone calls to be transferred. |
Failure
When it fails, the request returns the following error codes:
| HTTP Code | Code | Description |
|---|---|---|
| 400 | pc_phonecall_invalid | Value supplied in phoneCallId from the URI-Fragment is invalid. The parameter must be set to an alpha-numeric value and reference an existing phone call. |
| 400 | pc_sendcallto_invalid | Value supplied in sendCallTo parameter is missing or invalid. The parameter must be set to the number of a phone terminal extension. |
| 400 | pc_transfer_from_number_invalid | Value supplied in transferFromNumber parameter is missing or invalid. The parameter must be set to the value of a phone number. |
| 400 | pc_transfer_number_invalid | Value supplied in transferNumber parameter is missing or invalid. The parameter must be set to the value of a phone number. |
Response Body
If any 4xx or 5xx status codes is returned, the body contains the error response. When the request is successful and 200 OK is returned, the body contains a JSON representation.
Example
Below you can find an example that will help you understand the request and the response.
This example transfers a phone call of Extension 0003*210 to the Voicemail of 0003*024. The request is made by an App on behalf of a User.
PUT /uapi/phoneCalls/12/0003*210/444444
HTTP/1.1
HOST uapi.voipnow.com
Content Type: application/json
Authorization: Bearer token
{
"action": "TransferToVoicemail",
"sendCallTo": "0003*024",
"transferFromNumber": "0003*024"
}
Assuming that the request has been successful, the Service sends the following answer:
HTTP/1.1 202 Accepted
...
{
"id":"b817d2618fe6f1804333",
"extension":"0003*210",
"link":{"self":"https://x.x.x.x//uapi/phoneCalls/12/0003*210/b817d2618fe6f1804333"}
}
Use the link returned by the Service to list the details of the PhoneCall making a List PhoneCalls request. The list request outputs the following:
HTTP/1.1 200 OK
...
{
"id":"b817d2618fe6f1804333",
"extension":"0003*210",
"ownerId":"3",
"ownerName":"Default Organization",
"answered":"2012-06-27T16:08:55+03:00",
"published":"2012-06-27T16:08:50+02:00",
"phoneCallView":[
{
"id":"01",
"extension":"0003*210",
"answered":"2012-06-27T16:08:55+03:00",
"status":"5",
"callerId":"John Doe <3334444>",
"source":["0003*210"],
"destination":["0003*024"]
}
],
"link":{"self":"https://x.x.x.x//uapi/phoneCalls/12/0003*210/b817d2618fe6f1804333"}
}
Except where otherwise noted, content in this space is licensed under a Creative Commons Attribution 4.0 International.