This method allows putting PhoneCalls on hold in particular contexts such as User, Organization or global. |
Use this request to put a phone call on hold.
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.
The request is made by an App that is registered to a User account.
To put a phone call on hold, 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/b817d2618fe6f1804333
HTTP/1.1
HOST |
This section describes how to format the request to the service.
The following parameters must be sent in the URI fragment:
Name | Type | Required | Description |
---|---|---|---|
userId | Yes | The Id of the User that owns the Extension involved in the call. | |
extension | Yes | Number of the Extension involved in the call. | |
phoneCallId | Yes | Id of a PhoneCall resource that must be updated. |
When putting PhoneCalls on hold, 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 OnHold. |
phoneCallViewId | String | Yes | The PhoneCallView that is subject to the update. |
If successful, the Service returns the PhoneCall that was updated and the following HTTP statuses:
HTTP Code | Description |
---|---|
200 | The phone call is returned. |
204 | There is no phone call to be returned. |
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_phonecallview_invalid | Value supplied in phoneCallViewId parameter is missing or invalid. The parameter must reference a view of the phone call identfied by the phoneCallId given in the URI-Fragment. |
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.
Below you can find an example that will help you understand the request and the response.
This example puts the phone number 0003*024 on hold. The phoneCallViewId is set to 01, identifying the view of 0003*024. The request is made by an App on behalf of a User.
PUT /uapi/phoneCalls/12/0003*210/b817d2618fe6f1804333 HTTP/1.1 HOST uapi.voipnow.com Content Type: application/json Authroization: Bearer token { "action": "OnHold", "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 <3333>", "source":["0003*210"], "destination":["0003*024"] "onhold":"2012-06-27T16:18:55+23:00", "holder":1 } ] "link":{"self":"https://x.x.x.x//uapi/phoneCalls/12/0003*210/b817d2618fe6f1804333"} } |