PhoneCalls Service
The PhoneCall Service is used for real-time phone calls management. It allows making new phone calls, hanging up ongoing phone calls, transferring, recording, putting phone calls on hold, etc.
This service is available to Apps registered to the following account types:
Administrator
Organization
User
Base URL
https://{domain}/uapiEndpoints
| Method | Endpoint | Description |
|---|---|---|
| POST | /phoneCalls/{userId}/simple | Create Simple PhoneCalls |
| POST | /phoneCalls/{userId}/callback | Create Callback PhoneCalls |
| POST | /phoneCalls/{userId}/conferenceInvite | Create ConferenceInvite PhoneCalls |
| GET | /phoneCalls/{userId}/{extension}/{phoneCallId} | List PhoneCalls |
| PUT | /phoneCalls/{userId}/{extension}/{phoneCallId} | Update PhoneCalls |
| DELETE | /phoneCalls/{userId}/{extension}/{phoneCallId} | Delete PhoneCalls |
Create Simple PhoneCalls
This method allows making new PhoneCalls in particular contexts such as User, Organization or global. Use this request to make phone calls between two parties.
/phoneCalls/{userId}/simpleRequest
Path Parameters
| Parameter | Type | Required | Description | Default |
|---|---|---|---|---|
userId | string | Yes | Id of the User on behalf of whom the phone call is made. It can take one of the following values:
| - |
Query Parameters
| Parameter | Type | Required | Description | Default |
|---|---|---|---|---|
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. | 25 |
callDuration | number | No | Total duration of the call, in seconds. Default: global system value | - |
allowPublicTransfer | boolean | No | This flag restricts or permits transfer of a phone call made to a phone number external to the system. This flag is ignored for phone calls made to a local number. | false |
video | boolean | No | Enable video support in SDP. | false |
Authentication
This endpoint requires authentication via cookie or header token.
Payload
Request Payload
| Property | Type | Required | Description |
|---|---|---|---|
extension | object | No | Must refer to a Phone Terminal type Extension. Must be owned by the User identified by the userId sent in the URI-Fragment to @self and if missing the first value of the source is used. |
source | object | No | Can be set to a list of extension numbers or public numbers. |
destination | object | No | Can be any extension number or a public number. |
callerId | object | No | The caller name and number. It is displayed to the source. Default: The Caller Id of the Phone Terminal Extension. |
callerIdDestination | object | No | The caller name and number. It is displayed to the destination. |
nonce | object | No | A unique string which allows to identify the call created based on the request. |
Responses
200 OK
If successful, this method returns a 200 OK HTTP status code and array corresponding to the newly created phone calls.
Type: Array of object
Example Response
[
{
"id": "c3e92a04ff422a7a0b9f",
"extension": "0003*210",
"links": {
"self": "http://x.x.x.x/uapi/phoneCalls/@me/0003*210/c3e92a04ff422a7a0b9f"
}
}
]204 No Content
If there is no phone call to be returned, this method returns 204 No Content HTTP status code. It does not return anything in the response body.
400 Bad Request
If an error occurred, this API can return the standard Errors Codes or one the following:
Error codes:
Code Examples
cURL
curl 'https://api.hubgets.com/uapi/phoneCalls/@me/simple/' \
-H 'x-xsrf-token: 44HzZ6YIHDN6mbRY' \
-H 'content-type: application/json' \
-H 'cookie: dev=ffffffffffffffff2kjZMApYaH; xsrf-token=44HzZ6YIHDN6mbRY; vn=XI%2Cm-tpsEWgqBMBCNVpeAnUEaeqCpG7f' \
--data-binary '{"extension":"0003*210","phoneCallView":[{"source":["5354353","5302040"],"destination":["3235742879"],"callerId":"John Doe <4242425>"}]}'Create Callback PhoneCalls
Use this request to make a public call using a Callback Extension
/phoneCalls/{userId}/callbackRequest
Path Parameters
| Parameter | Type | Required | Description | Default |
|---|---|---|---|---|
userId | string | Yes | Id of the User on behalf of whom the phone call is made. It can take one of the following values:
| - |
Query Parameters
| Parameter | Type | Required | Description | Default |
|---|---|---|---|---|
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. | 25 |
callDuration | number | No | Total duration of the call, in seconds. Default: global system value | - |
video | boolean | No | Enable video support in SDP. | false |
Authentication
This endpoint requires authentication via cookie or header token.
Payload
Request Payload
| Property | Type | Required | Description |
|---|---|---|---|
extension | object | No | Must refer to a Callback Extension. Must be owned by the User identified by the userId sent in the URI-Fragment to @self and if missing the first value of the source is used. |
source | object | No | A public phone number. |
destination | object | No | A public phone number.. |
callerId | object | No | The caller name and number. It is displayed to the source. Default: The Caller Id of the Phone Terminal Extension. |
callerIdDestination | object | No | The caller name and number. It is displayed to the destination. |
nonce | object | No | A unique string which allows to identify the call created based on the request. |
Responses
200 OK
If successful, this method returns a 200 OK HTTP status code and the id of the newly created PhoneCall. The Id can be used later to query the status of the phone call, hang it up or update it using the available actions.
Type: Array of object
Example Response
[
{
"id": "c3e92a04ff422a7a0b9f",
"extension": "212",
"link": {
"self": "http://x.x.x.x/uapi/phoneCalls/@me/212/c3e92a04ff422a7a0b9f"
}
}
]204 No Content
If there is no id to be returned, this method returns 204 No Content HTTP status code. It does not return anything in the response body.
400 Bad Request
If an error occurred, this API can return the standard Errors Codes or one the following:
Error codes:
Code Examples
cURL
curl 'https://api.hubgets.com/uapi/phoneCalls/@me/callback/' \
-H 'x-xsrf-token: 44HzZ6YIHDN6mbRY' \
-H 'content-type: application/json' \
-H 'cookie: dev=ffffffffffffffff2kjZMApYaH; xsrf-token=44HzZ6YIHDN6mbRY; vn=XI%2Cm-tpsEWgqBMBCNVpeAnUEaeqCpG7f' \
--data-binary '{"extension":"212","phoneCallView":[{"source":["3334444"],"destination":["3235742879"],"callerId":"John Doe <4242425>"}]}'Create ConferenceInvite PhoneCalls
Use this request to call a public or local phone number and connect it to a conference call.
/phoneCalls/{userId}/conferenceInviteRequest
Path Parameters
| Parameter | Type | Required | Description | Default |
|---|---|---|---|---|
userId | string | Yes | Id of the User on behalf of whom the phone call is made. It can take one of the following values:
| - |
Query Parameters
| Parameter | Type | Required | Description | Default |
|---|---|---|---|---|
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. | 25 |
callDuration | number | No | Total duration of the call, in seconds. Default: global system value | - |
video | boolean | No | Enable video support in SDP. | false |
number | number | No | Represents the number of the scheduled conference to which the destination is invited. If not supplied, the user is asked to enter it. | - |
pin | string | No | Represents the PIN of the scheduled conference to which the destination is invited to. If not supplied, the user is asked to enter it . | - |
Authentication
This endpoint requires authentication via cookie or header token.
Payload
Request Payload
| Property | Type | Required | Description |
|---|---|---|---|
extension | object | No | Must refer to a Conference type Extension. Must be owned by the User identified by the userId sent in the URI-Fragment to @self and if missing the first value of the source is used. |
source | object | No | Must equal to the value of the extension and must reference a Conference extension. |
destination | object | No | Can be any extension number or a public number. |
callerId | object | No | The caller name and number. It is displayed to the source. Default: The Caller Id of the Conference Extension. |
callerIdDestination | object | No | The caller name and number. It is displayed to the destination. |
nonce | object | No | A unique string which allows to identify the call created based on the request. |
Responses
200 OK
If successful, this method returns a 200 OK HTTP status code and the id of the newly created PhoneCall. The id can be used later to query the status of the phone call, hang it up or update it using the available actions.
Type: Array of object
Example Response
[
{
"id": "99735c54ff45a3a988f2",
"extension": "211",
"link": {
"self": "http://x.x.x.x/uapi/phoneCalls/@me/211/99735c54ff45a3a988f2"
}
}
]204 No Content
If there is no id to be returned, this method returns 204 No Content HTTP status code. It does not return anything in the response body.
400 Bad Request
If an error occurred, this API can return the standard Errors Codes or one the following:
Error codes:
List PhoneCalls
This request lists the phone calls that are in the system at a given time.
/phoneCalls/{userId}/{extension}/{phoneCallId}Request
Path Parameters
| Parameter | Type | Required | Description | Default |
|---|---|---|---|---|
userId | string | Yes | Id of the User on behalf of whom the phone call is made. It can take one of the following values:
| - |
extension | string | Yes | Number of the extension involved in the call. Use @self to match all the extensions under the User. The list is availabel only for phone terminal extensions. | - |
phoneCallId | string | 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 PhoneCall Id can be retrieved using the List PhoneCalls request. | - |
Query Parameters
| Parameter | Type | Required | Description | Default |
|---|---|---|---|---|
count | count | No | - | |
filterBy | string | No | Records can be filtered by PhoneCall id and published date. | - |
filterOp | string | No | The parameter must be set to one of the values: equals, greaterThan, lessThan, present, startsWith, contains, inArray. | equals |
filterValue | string | No | The value to filter by. You can filter by the phone call id or the published date | - |
startIndex | startIndex | No | - | |
fields | fields | No | An array of PhoneCall properties to be returned. | - |
sortOrder | sortOrder | No | The sorting order of the results. The records are always ordered by their publish time. | - |
Authentication
This endpoint requires authentication via cookie or header token.
Responses
200 OK
If successful, this method returns a 200 OK HTTP status code and a collection of PhoneCall objects.
Example Response
{
"entry": [
{
"id": "b817d2618fe6f1804db1",
"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": "00",
"extension": "0003*210",
"answered": "2012-06-27T16:08:55+03:00",
"status": "5",
"callerId": "John Doe <3235742879>",
"source": [
"0003*210"
],
"destination": [
"3235742879"
],
"links": {}
}
]
}
],
"startIndex": 0,
"totalResults": 1,
"itemsPerPage": 20,
"filtered": false,
"sorted": false,
"paging": {}
}204 No Content
If there are no phone calls to be returned, this method returns 204 No Content HTTP status code. It does not return anything in the response body.
400 Bad Request
If an error occurred, this API can return the standard Errors Codes or one the following:
Error codes:
Update PhoneCalls
This method allows to update a phone call to Voicemail in particular contexts such as User, Organization or global. 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.
/phoneCalls/{userId}/{extension}/{phoneCallId}Request
Path Parameters
| Parameter | Type | Required | Description | Default |
|---|---|---|---|---|
userId | string | Yes | Id of the User on behalf of whom the phone call is made. It can take one of the following values:
| - |
extension | string | Yes | Number of the extension involved in the call. Use @self to match all the extensions under the User. The list is availabel only for phone terminal extensions. | - |
phoneCallId | string | 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 PhoneCall Id can be retrieved using the List PhoneCalls request. | - |
Authentication
This endpoint requires authentication via cookie or header token.
Payload
- ParkPhoneCalls
- UnParkPhoneCalls
- OnHoldPhoneCalls
- OffHoldPhoneCalls
- StartRecordingPhoneCalls
- StopRecordingPhoneCalls
- PickupPhoneCalls
- BargeInPhoneCalls
- WhisperPhoneCalls
- MonitorPhoneCalls
- TransferPhoneCalls
- TransferToVoiceMailPhoneCalls
Responses
200 OK
If successful, this method returns a 200 OK HTTP status code and the PhoneCall that was updated.
Response
| Property | Type | Required | Description |
|---|---|---|---|
id | string | Yes | |
extension | string | Yes | |
links | Link | No |
Example Response
{
"PhoneCall": {
"id": "b817d2618fe6f1804333",
"extension": "0003*210",
"link": {
"self": "https://x.x.x.x/uapi/phoneCalls/12/0003*210/b817d2618fe6f1804333"
}
}
}204 No Content
If there are no phone calls to be returned, this method returns 204 No Content HTTP status code. It does not return anything in the response body.
400 Bad Request
If an error occurred, this API can return the standard Errors Codes or one the following:
Error codes:
401 Unauthorized
If the value supplied in the URI-Fragment as userId lacks the proper permissions for the requested operation, this API can return the standard Errors Codes or one the following:
Error codes:
501 Not Implemented
If the value supplied in action parameter is not implemented, this API can return the standard Errors Codes or one the following:
Error codes:
Code Examples
cURL
curl 'https://api.hubgets.com/uapi/phoneCalls/12/0003*210/444444/' \
-X 'PUT' \
-H 'x-xsrf-token: 44HzZ6YIHDN6mbRY' \
-H 'content-type: application/json' \
-H 'cookie: dev=ffffffffffffffff2kjZMApYaH; xsrf-token=44HzZ6YIHDN6mbRY; vn=XI%2Cm-tpsEWgqBMBCNVpeAnUEaeqCpG7f' \
--data-binary '{"action":"TransferToVoicemail","sendCallTo":"0003*024","transferFromNumber":"0003*024"}'Delete PhoneCalls
Use this request to hang up an existing phone call.
/phoneCalls/{userId}/{extension}/{phoneCallId}Request
Path Parameters
| Parameter | Type | Required | Description | Default |
|---|---|---|---|---|
userId | string | Yes | Id of the User on behalf of whom the phone call is made. It can take one of the following values:
| - |
extension | string | Yes | Number of the extension involved in the call. Use @self to match all the extensions under the User. The list is availabel only for phone terminal extensions. | - |
phoneCallId | string | 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 PhoneCall Id can be retrieved using the List PhoneCalls request. | - |
Authentication
This endpoint requires authentication via cookie or header token.
Payload
Request Payload
| Property | Type | Required | Description |
|---|---|---|---|
phoneNumber | string | No | Phone number of one of the parties involved in the phone call. When given, the number involved in the phone call and the Extension are closed. |
Responses
200 OK
If successful, this method returns a 200 OK HTTP status code and a list of the PhoneCalls objects that have just been hung up.
Type: Array of object
Example Response
[
{
"id": "7d280cc4feae3255a497"
}
]204 No Content
If there are no phone calls to be returned, this method returns 204 No Content HTTP status code. It does not return anything in the response body.
400 Bad Request
If an error occurred, this API can return the standard Errors Codes or one the following:
Error codes:
Code Examples
cURL
curl 'https://api.hubgets.com/uapi/phoneCalls/@me/0003*210/7d280cc4feae3255a497/' \
-H 'x-xsrf-token: 44HzZ6YIHDN6mbRY' \
-H 'content-type: application/json' \
-H 'cookie: dev=ffffffffffffffff2kjZMApYaH; xsrf-token=44HzZ6YIHDN6mbRY; vn=XI%2Cm-tpsEWgqBMBCNVpeAnUEaeqCpG7f' \
--data-binary '{"phoneNumber":"8887777"}'