Request/Response model
Overview
Use this request to barge in on an existing phone call. The request is very useful when you want to intercept the conversation of a queue agent with a customer.
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 made by an App that is registered to a User account.
To barge in on a phone 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/b817d2618fe6f1804333
HTTP/1.1
HOST uapi.voipnow.com
Content Type: application/json
Authorization: Bearer token
{
"action": "BargeIn",
"sendCallTo": "0003*024",
"callerId": "John Doe <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:
| Name | Type | Required | Description |
|---|---|---|---|
userId | Yes | Id of the User that owns the Extension involved in the call. | |
extension | Yes | The number of the Extension involved in the call. | |
phoneCallId | Yes | Id of a PhoneCall resource that must be updated. |
Request Payload
When barging in on a 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 BargeIn. |
| sendCallTo | Yes | Number of the extension that will barge in. Must be in the same Organization as the Extension given in the URI-Fragment. Must refer to a Phone Terminal Extension. | |
| callerId | UAPI-Caller-Id | No | The caller name and number. It is displayed to the source. Default: the callerId of the Phone Terminal Extension. |
| waitForPickup | Number | No | The 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. |
| phoneCallViewId | String | Yes | The PhoneCallView that is subject to the update. |
Response
Success
If successful, the request 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. |
Response
When it fails, the request returns the following error codes:
| HTTP Code | Code | Description |
|---|---|---|
| 400 | pc_timeout_invalid | Value supplied in waitForPickup parameter is missing or invalid. The parameter must be numeric and higher than 0. |
| 400 | pc_callerid_invalid | Value supplied in callerId parameter is missing or invalid. The parameter must be set to a value with the format: John Doe <+3334444>. |
| 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. |
| 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. |
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.
Examples
Below you can find an example that will help you understand the request and the response.
0003*024 is the number of the Extension that barges in. The Service calls 0003*024 first and displays the Barge In <42420042> as caller Id. After 0003*024 responds, it is connected to 0003*210 and can join the conversation.
The phoneCallViewId identifies the phone call that is connected to. 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/b817d2618fe6f1804333
HTTP/1.1
HOST uapi.voipnow.com
Content Type: application/json
Authorization: Bearer token
{
"action": "BargeIn",
"sendCallTo": "0003*024",
"callerId": "John Doe <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 <444555>",
"source":["777888"],
"destination":["0003*210"]
}
{
"id":"02",
"extension":"0003*210",
"answered":"2012-06-27T16:08:55+03:00",
"status":"5",
"callerId":"Barge In <3334444>",
"source":["0003*024"],
"destination":["0003*210"]
}
]
}
Except where otherwise noted, content in this space is licensed under a Creative Commons Attribution 4.0 International.