Page tree
Skip to end of metadata
Go to start of metadata
This page describes the representation of the resources used by the PhoneCall Service.

PhoneCall resource

A phone call is represented by UnifiedAPI as a PhoneCall resource and contains the PhoneCallView components which describes the phone call from the perspective of the parties involved in the phone call.

JSON representation

The example below contains the PhoneCall in JSON representation. All fields are fictitious.

{
  "id": "b817d2618fe6f1804333",
  "nonce": "130c5a97768be67df6543b5f5fa3cc51",
  "extension": "0003*210",
  "ownerId": "53tete535",
  "ownerName": "53tete535",
  "published": "2011-02-10T15:04:55Z",
  "answered": "2011-02-10T15:10:55Z",
  "phoneCallView": [
    {
        "id":"00",
        "extension":"0003*210",
        "source":["0003*211","0003*210"],
        "destination":["3334444"],
        "flow":4,
        "status":3,
        "ringing":"2011-02-10T15:04:55Z",
        "callerID":"John Doe <3332222>",
    },
    {
        "id":"01",
        "extension":"0003*211",
        "source":["0003*211","0003*210"],
        "destination":["3334444"],
        "flow":4,
        "status":3,
        "ringing":"2011-02-10T15:04:55Z",
        "callerID":"John Doe <3332222>",
    }
  ],
  "links": { 
	"self": "..." 
  }
}

When a HTTP response is returned by the Service, the fields that are NULL are not included in the response!

PhoneCall specific fields

The table below describes the fields that are specific to the PhoneCall resource and are not to be found in the PhoneCallView or PhoneCallLink.

NameTypeCan be NULLDescription
idObject-IdNoThe Id of the PhoneCall as saved in the system. The Id is generated by the Service and can be later used to list or edit the PhoneCall details.
extensionUAPI-Extension-NumberNoThe number of the Extension that is charged for the phone call. This Extension might not be a party of the phone call.
ownerIdUser-IdNoThe Id of the Organization that owns the PhoneCall.
ownerNameStringNoThe name of the Organization that owns the PhoneCall.
publishedDateNoThe date the phone call entered the system.
answeredDateYesThe date the phone call was answered.
nonceStringNo

A unique string which allows to identify the call created based on the request.

PhoneCallView fields

The table below describes the fields of a PhoneCallView component.

NameTypeCan be NULLDescription
idObject-IdNoThe Id of the PhoneCallView as generated by the Service. The Id of the view can be used later to edit the call.
extensionUAPI-Extension-NumberNoThe phone number of the Extension. The PhoneCallView is from the perspective of this extension.
sourceArray< UAPI-Extension-Number | UAPI-Phone-Number >NoThe phone number of the source.
destinationArray< UAPI-Extension-Number | UAPI-Phone-Number >NoThe phone number of the destination.
flowNumberNo

The flow of the call, which is set to:

2 - a local call
4 - an outgoing public call
8 - an incoming public call

statusNumberNo

The status of the call, which is set to:

0 - unknown
1 - off hook
2 - trying
3 - ringing
4 - other side is ringing
5 - on call

ringing Date YesThe date when the source terminal started ringing.
Can be missing if the call is answered.
callerIdUAPI-Caller-IdYesThe caller Id.
recording Date Yes

The date when the phone call started to be recorded.
Can be missing if the call is not recorded.

answered Date YesThe date the source answered the call.
Can be missing if the call is ringing.
parked Date Yes

The date when the phone call was parked.
Can be missing if the call is not parked.

parkedPosNumberYesThe position of the call in the parking lot.
parkedByUAPI-Extension-NumberYesThe number that put the phone call in the parking lot.
onHold Date YesThe date the phone call was put on hold.
holderNumberYesIf set to 1, this peer put the phone call on hold.
dispositionNumberYes

The call disposition:
0 - ANSWERED - to fetch calls that were answered
1 - BUSY - to get the calls that were answered with a busy tone
2 - FAILED - to fetch the calls that have failed
3 - NO ANSWER - to fetch the calls that had no answer
4 - UNKNOWN - to fetch the unknown calls
5 - NOT ALLOWED - to fetch the calls that were not allowed.

spyingNumberYes

This flag is set to 1 if the extension is spying it's peer.
This can be the case when a barge in or whisper is attempted.

queueUAPI-Extension-NumberYesThe phone number of the queue extension. Used when a call is routed using a queue.
Example

If we have a call between two phone numbers 0003*210 and 0003*211 and 0003*210 records the call, the PhoneCallViews will look as in the example below:

{
  "id": "b817d2618fe6f1804333",
  "extension": "0003*210",
  ....
  "phoneCallView': [
    {
        "id":"00",
        "extension":"0003*210",
        ....
        "recording": "2012-06-20T09:55:13+03:00" //The call of 0003*210 is being recorded

    },
    {
        "id": "01",
        "extension": "0003*211",
        ...
	   // The call of 0003*211 is not recorded so the recording parameter is missing
    }
  ],
 links: { 
	...
  }
}

PhoneCallAction object

During its lifetime, a phone call can be put on hold, parked, recorded or manipulated using other actions. These actions are represented as the PhoneCallAction object by UnifiedAPI.

JSON representation

The example below contains the PhoneCallAction in JSON representation. All fields are fictitious.

{
   "action": "PickUp",
   "sendCallTo": "0003*210*, 
   "callerId: "John Doe <42420042>",
   "waitForPickup": "20" ,
   "phoneCallViewId": "zz"
}

Fields that are NULL are not included in the answer!

Resource specific fields

The table below describes the fields that are specific to the PhoneCallAction object.

NameTypeDescription
actionString

The type of action to perform. Possible values:

  • OnHold
  • OffHold
  • StartRecording
  • StopRecording
  • PickUp
  • BargeIn
  • Park
  • UnPark
  • Whisper
  • Transfer
  • TransferToVoicemail
sendCallToSome actions need a phone number to send the call to. This field should contain the number.
callerId UAPI-Caller-Id When a call is barged in or is whispered on, a caller Id can be sent to the Service.
waitForPickUpNumberThe maximum number of seconds to wait until one of the phone numbers used picks up.
As soon as the set time value runs out, the call is canceled.
Default: 25 seconds.
phoneCallViewIdStringThe Id of PhoneCallView that is subject to the change.
formatStringUsed only when recording a phone call and must be set to the format of the recorded file.

Except where otherwise noted, content in this space is licensed under a Creative Commons Attribution 4.0 International.