API Version: 6.4

IPCortex.Types.Device

A Device instance represents a phone line/identity.
It may be a button on a handset, a keevio phone line, or sometimes a SIP/IAX/ISDN trunk. It acts as a parent/container for any active calls that exist on that line. A Device which is part of a handset will be contained in a Phone instance.

Properties

Name Type Description
name String Device name e.g. SIP/abc (Unique key)
label String The name of this line/device. Determined by PABX configuration, this represents the same value as would be shown on a handset display.
extension String The number of this line/device. Determined by PABX configuration, this may be displayed on the handset, and is used as the default caller ID for calls originated on the device.
extensions Array A list of Extension instances that call this device.
queues Object A keyed list of Queue instancess that call this device. The value is the device's Queue state (inuse, paused, idle etc).
optOut Array A list of opted out extensions.
mailbox Mailbox The primary mailbox.
webrtc Boolean True if the device is webrtc capable.
webrtcState String webRTC state if the device is webrtc capable.
  • none - Not a webRTC device.
  • inactive - not enabled.
  • remote - enabled for remote mode.
  • disconnected - enabled but currently disconnected.
  • unregistered - enabled and connected but currently unregistered.
  • registered - enabled and working.
phone Phone The container Phone for this device (may be null) 6.3+
owner Contact Owners contact instance or null if unowned. Taken from Phone above. 6.4.27+
ownerID Number Owners contact ID or null if unowned. Taken from Phone above. 6.4.27+
calls Array A list of active Call instances.
mac String The identifier for this device, based on the MAC address. All lines/identities will have the same identifier.
features String Comma separated list of features.
  • hold
  • talk
  • answer
state String Device state.
  • unknown
  • down
  • up
blf Number Line/Identity state indication.
  • 0 - available
  • 1 - on call
  • 2 - ringing
  • 3 - on call and ringing

Settable properties

Name Type Description
autoanswer Boolean Ask the handset to autoanswer API initiated calls.
autohold Boolean Try to 'force' the above behaviour. Hold existing calls.
microphone String A device ID string for microphone (WebRTC only).

Methods

device.dial(address, [callback]) ⇒ Promise

device.dial(contact, [callback]) ⇒ Promise

device.dial(extension, [callback]) ⇒ Promise

Kind: class method of IPCortex.Types.Device
Dial a number, as per the methods below, but use the number from the relevant Address, Contact or Extension Class to determine the number.
Name Type Description
address Address Address object which identifies the number to dial.
contact Contact Contact object which identifies the number to dial.
extension Extension Extension object which identifies the number to dial.

device.dial(number, [autohold], [autoanswer], [callback]) ⇒ Promise

device.dial(number, [callback]) ⇒ Promise

device.dial(options, [callback]) ⇒ Promise

Kind: class method of IPCortex.Types.Device
Dial a number. The success/fail callback only represents whether the call request was sent to the PABX, and was not immediately rejected. Whether the call progresses to completion is independent of a success result. On the other hand, the promise will only resolve if the call progresses, and it should normally resolve with the call object for the outbound call.
Name Type Description
number Boolean Ask the handset to autoanswer API initiated calls.
autohold Boolean Try to 'force' the above behaviour. Hold existing calls.
autoanswer Boolean Ask the handset to autoanswer API initiated calls.
options Object Object describing dial options

device.opt(extensions, [callback])

Kind: class method of IPCortex.Types.Device
Opt in or out of an extension.
Name Type Description
extensions Object Object describing opt-in or -out extensions

device.enableRTC() ⇒ Promise

Kind: class method of IPCortex.Types.Device Returns: Promise which resolves with no data once succeeded.
Enable/register the webrtc device if the webrtc property is true.

device.reEnableRTC(best_efforts) ⇒ Promise

Kind: class method of IPCortex.Types.Device Returns: Promise which resolves with no data once succeeded.
Only useful after a call to enableRTC. This causes a password refresh and a close/open/re-register attempt.
Name Type Description
best_efforts Boolean If any issues occur, do not error, try to leave JsSIP in a 'running' state
NOTE: If best_efforts is false and any intermediate steps fail, the Promise will reject, and JsSIP will be left effectively 'paused'.

device.pauseRTC() ⇒ Promise

Kind: class method of IPCortex.Types.Device Returns: Promise which resolves with no data once succeeded.
Only useful after a call to enableRTC. This de-registers and closes the socket; Use reEnableRTC() to restart the connection.

device.disableRTC()

Kind: class method of IPCortex.Types.Device
DisEnable/Unregister the webrtc device if the webrtc property is true. Cancel RTCRemote if enabled.

device.register()

Kind: class method of IPCortex.Types.Device
Cause the webrtc device to re-register immediately.

device.enableRTCRemote()

Kind: class method of IPCortex.Types.Device
As long as Chat is enabled, disables webRTC for this device and instead sends remote keevio Command requests in the hope that a keevio instance will handle them. The far end needs to have the keevio-command channel enabled in order to receive these instructions.
This is useful in cases where an application wants to use keevio-phone, but the user is alreay running another application that has used/reserved that keevio-phone instance, such as keevio itself. Enabling this feature is often as simple as replacing:
myPhone.enableRTC();
with
IPCortex.PBX.enableChat();
myPhone.enableRTCRemote();
Operations that are currently supported are:
  • device.dial()
  • call.talk()
  • call.hold()
  • call.hangup()
  • call.mute()
  • call.dtmf()
Operations that are NOT currently supported are:
  • call.xfer()
  • call.atxfer()

device.history(enable)

Kind: class method of IPCortex.Types.Device
Enable or disable call history for the device. If call history for this device has been loaded but not sent to the client app, then enabling history will cause all saved events to be sent in order.
Name Type Description
enable Boolean true: enable history on Device, false: disable history on Device

device.addListener(event, callback)

Kind: class method of IPCortex.Types.Device
Add listener method, inherited from Api base class and common to all classes.
Parameter Type Description
event String Name of event, e.g. 'update'
callback Function Callback which is passed a reference to the updated Class object

device.removeListener(event, callback)

Kind: class method of IPCortex.Types.Device
Remove listener method, inherited from Api base class and common to all classes. event and callback must be identical to those used in addListener() in order for the remove to succeed.
Parameter Type Description
event String Name of event, e.g. 'update'
callback Function Callback which is passed a reference to the updated Class object

Events

  • new - A new device is created.
  • update - The device state, or its Call(s) have changed.