This method allows a third-party to whisper on call in particular contexts such as User, Organization or global.

Request/Response model

Overview

Use this request to whisper to a party involved in a phone call.

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

The request is very useful when you want to intercept the conversation of a queue agent with a customer.

The request is made by an App that is registered to a User account.

To whisper on a call 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
PUT /uapi/phoneCalls/12/0003*210/444444
HTTP/1.1
HOST uapi.voipnow.com
Content Type: application/json
Authorization: Bearer token

{
  'action":"Whisper",
  "sendCallTo":"0003*024*,
  "private":0, 
  "callerId":"Whisper To Me <42420042>",
  "waitForPickup":"20",
  "phoneCallViewId":"01"
}


Request

This section describes how to format the request to the service.

URI fragment

The following parameters must be sent in the URI fragment:

NameTypeRequiredDescription

userId

User-Id

Yes

Id of the User that owns the an 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

The 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 parked.
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 whispering on a PhoneCall, the following restrictions apply to the PhoneCall resource sent in the Request Payload:

NameTypeRequiredDescription
actionStringYesAction must be set to Whisper.
sendCallTo UAPI-Extension-Number YesNumber of the Extension that will whisper.
Must be in the same Organization as the Extension given in the URI-Fragment.
Must refer to a Phone TerminalExtension.
callerId UAPI-Caller-Id NoThe caller name and number.
It is displayed to the source.
Default: the callerId of the Phone Terminal Extension.
waitForPickupNumberNoThe maximum number of seconds to wait until one of the phone numbers used picks up.
When the time value set here runs out, the call is cancelled.
Default: 25 seconds.
phoneCallViewIdStringYesThe PhoneCallView that suffers the update.
privateNumberNoWhen set to 1, the extension that whispers does not hear the conversation between the the parties involved in the call.
Possible values: 0 and 1.
Default 0.

Response

Success

HTTP CodeDescription
200The phone call is returned.
204There is no phone call to be returned.

Failure

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

HTTP CodeCodeDescription
400pc_timeout_invalidValue supplied in waitForPickup parameter is missing or invalid. The parameter must be numeric and higher than 0.
400pc_callerid_invalidValue supplied in callerId parameter is missing or invalid. The parameter must be set to a value with the format: John Doe <+3334444>.
400pc_honecall_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_private_invalidValue supplied in private parameter is missing or invalid. The parameter must be set to 0 for non private calls or 1 for private calls.
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.

Extension 0003*024 whispers to Extension 0003*210. The Service calls 0003*024 first and displays the Whisper To Me <42420042> as caller Id.

As soon as 0003*024 responds, it is connected to 0003*210 and can whisper to the conversation.

The phoneCallViewId identifies the phone call that is listened. Once the connection is made, the 02 phoneCallView is created. 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":"Whisper",
  "sendCallTo":"0003*024*,
  "private":0, 
  "callerId":"Whisper To Me <42420042>",
  "waitForPickup":"20",
  "phoneCallViewId":"01"
}

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":["7778888"],
       "destination":["0003*210"]
     }

	  {
       "id":"02",
       "extension":"0003*210",
       "answered":"2012-06-27T16:08:55+03:00",
       "status":"5", 
       "callerId":"Whisper To Me <42420042>",
       "source":["0003*024"],
       "destination":["0003*210"]
     }
 ]
}