Transfer PhoneCalls

This method allows transferring a phone call to another number in particular contexts such as User, Organization or global.

Request/Response model

Overview

Use this request to transfer a phone call to a third-party phone number.

The request identifies the phone call using the User Id, Extension number, and PhoneCall Id. If successful, it returns the PhoneCall that was updated.

UnifiedAPI can also transfer the phone call to voicemail. The request is made by an App that is registered to a User account.

To transfer a phone call to another number in a desired context, issue a HTTP PUT request:

Model

HTTP-Method       = "PUT"
URI-Fragment      = "/uapi/phoneCalls/" User-Id "/" Extension-Number "/" PhoneCall-Id
Query-Parameters  = null 
Request-Payload   = PhoneCallAction

Return-Object     = PhoneCall

Example

PUT /uapi/phoneCalls/12/0003*210/b817d2618fe6f1804333
HTTP/1.1
HOST uapi.voipnow.com
Content Type: application/json
Authorization: Bearer token

{
  "action":"Transfer",
  "sendCallTo":"3334444",
  "transferFromNumber":"0003*024",

  "transferNumber":"0003*210"
}

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	User-Id	Yes	Id of the User that owns the Extension involved in the call. It can take one of the following values: @me - refers to the authenticated User . @viewer - also refers to the authenticated User . @owner - refers to the User that owns the Extension used to make the phone call. User-Id - refers to the unique identifier of the User. Default: @me
extension	UAPI-Extension-Number	Yes	Number of the Extension involved in the call. Use @self to match all the extensions under the User.
phoneCallId	Object-Id	Yes	Id of a PhoneCall resource that must be updated. If not provided, all phone calls owned by Extension are transferred. If the Extension is unknown, you can use @self and phoneCallId to identify the phone call. The PhoneCallId can be retrieved using the List PhoneCalls request.

Request Payload

When transferring the PhoneCall, 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 Transfer.
sendCallTo	UAPI-Extension-Number	Yes	Phone number where the call is transferred. Can be an extension number or a public number.
transferFromNumber	UAPI-Extension-Number	Yes	The phone number of the party that transfers the call. Its value can be the phone number of the source or destination.
transferNumber	UAPI-Extension-Number	No	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 request returns returns the PhoneCall that was updated and the following HTTP statuses:

HTTP Code	Description
200	The phone call is returned.
204	There are no phone calls to be returned.

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 the phone call of Extension 0003*210 to 0003*024 to the public number 3235742879. The request is made by an App on behalf of a User.

HTTP Request

PUT /uapi/phoneCalls/12/0003*210/b817d2618fe6f1804333
HTTP/1.1
HOST uapi.voipnow.com
Content Type: application/json
Authorization: Bearer token

{
  "action":"Transfer",
  "sendCallTo":"3235742879",
  "transferFromNumber":"0003*024",
  "transferNumber":"0003*210"
}

Assuming that the request has been successful, the Service will send the following answer:

HTTP Response

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 PhoneCall request. The list request outputs the following: