Page tree

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Updated using 4PSA automated script
Excerpt

This method allows to transfer a phone call to Voicemail in particular contexts such as User, Organization or global.

Table of Contents
maxLevel3
excludeApps Using This, Quick Examples, Need Help?

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:

Panel
borderColor#DADADA
bgColor#FFFFFF
titleBGColor#F0F0F0
borderWidth1
titleModel
borderStyledashedtitleModel
HTTP-Method       = "PUT"
URI-Fragment      = "/uapi/phoneCalls/" User-Id "/" Extension-Number "/" PhoneCall-Id
Query-Parameters  = null 
Request-Payload   = PhoneCallAction
Return-Object     = PhoneCall
Panel
borderColor#DADADA
bgColor#FFFFFF
titleBGColor#F0F0F0
borderWidth1
titleExample
borderStyledashedtitleExample

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

Anchor
urifragment
urifragment

The following parameters must be sent in the URI fragment:

NameTypeRequiredDescription

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

es

Number of the Extension involved in the call.
Use @self to match all the extensions under the User.

phoneCallId

Object-Id

Yes

Specifies the Id of a PhoneCall resource that must be updated, otherwise all PhoneCall resources of the extension will be updated.
If the Extension is unknown, you can use @self and phoneCallId to identify the phone call.

Request Payload

Anchor
reqpayload
reqpayload

When transferring a PhoneCall to Voicemail, the following restrictions apply to the PhoneCall resource sent in the Request Payload:

NameTypeRequiredDescription
actionStringYesAction must be set to TransferToVoicemail.
sendCallTo UAPI-Extension-Number YesNumber 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.
phoneCallViewIdStringYesThe PhoneCallView that is subject to the update.

Response

Success

If successful, the Service returns the PhoneCall that was updated and the following HTTP statuses:

HTTP CodeDescription
200The phone call is transferred.
204There are no phone calls to be transferred.

Failure

When it fails, the request returns the following error codes:

HTTP CodeCodeDescription
400pc_phonecall_invalidValue 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.
400pc_phonecallview_invalidValue supplied in phoneCallViewId parameter is missing or invalid. The parameter must reference a view of the phone call identified by the phoneCallId given in the URI-Fragment.
400pc_sendcallto_invalidValue supplied in sendCallTo parameter is missing or invalid. The parameter must be set to the number of a phone terminal extension.

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.

Anchor
phcall-ex1
phcall-ex1

Code Block
titleHTTP Request
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",
  "phoneCallViewId": "01"  
}

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

Code Block
titleHTTP 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 PhoneCalls request. The list request outputs the following:

Code Block
titleHTTP Response
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.