NAV
javascript

Introduction

EnreachClientAPI (later API) provides a local websocket server with a JSON-RPC 2.0 interface to workstation-level functions.

API provides access to underlying telephone software (Lync, Skype for Business or Voice for Windows), later referred to as phone. API is identical for all underlying phones unless otherwise specified.

API consists of a single Windows executable and auxiliary libraries. In normal deployments, it is included in Voice for Windows software package and started automatically with it.

API provides no visible user interface. It listens for connections silently in background. It listens for incoming connections from localhost. Connections may be authorized by Origin mechanism, so only certain domains may access the functionality.

Log file is created in temporary directory %TEMP%\BAPIWS_yyyymmdd.log.

Note that Benemen was renamed to Enreach in 2022, and corresponding naming changes were applied to technical products and documentation as well. Some documentation and technical details may still contain Benemen references.

Configuration

When working with Voice for Windows, the API receives it's configuration automatically.

For standalone deployments, registry configuration is used instead. Port and allowed origins are configured in local registry under key:

HKEY_LOCAL_MACHINE/Software/Benemen/BAPIWS

Key name Description
Port Specifies the local port for incoming connections. Default value 9898
AllowedOrigins Specifies web domain connections are allowed from, for example “company.com”. Default value is "*", meaning that connections from all domains are allowed.

JSON-RPC

API uses JSON-RPC 2.0 for communication. See json-rpc.org for complete description. The most relevant parts are given below.

Request

Request object is sent to the server. It has the following members:

{
    "jsonrpc": "2.0",
    "id": 1455629097084,
    "params": ["Parameter"],
    "method": "DoSomething"
}
Member Description
jsonrpc Version of the JSON-RPC protocol. MUST be "2.0".
method Name of the method (see methods)
params parameters as specified by the method
id An id for correlating request and response. Server sends responses with the same id. An incrementing integer is a good start.

Response

When the server responds to a request, it responds with a Response object. It has the following members:

{
    "jsonrpc": "2.0",
    "result": 0,
    "id": 1455629097084
}
Member Description
jsonrpc Version of the JSON-RPC protocol. MUST be "2.0".
result Result value. Not returned if there was an error.
error Error description. Not returned on success.
id Id of the request response relates to

Notification

A Notification is a Request object without an "id" member. A Notification means that the sender is not interested in a response (and that it cannot be responded to).

{
    "jsonrpc": "2.0",
    "method": "SomethingHappened",
    "params": ["What","Coffee"]
}

Interface

General

Timeout

BAPIWS may timeout connections without activity after a period of time. Persistent clients should implement a keep-alive call, periodically sending a request to the server. This is easiest to do with a simple GetState call for example every 60 seconds.

CallID

CallID is client-side call id generated by the phone. Voice for Windows provides a unique GUID as call id, whereas Lync calls are referred to simple incremental id numbers.

This call id is separate from server-side call id handled when dealing with call recordings etc. It is meant for client side communication only.

Methods

Methods that can be invoked from client side. Each method accepts some parameters and later returns corresponding result.

Init

Send message

{
    "jsonrpc": "2.0",
    "id": 1455629097083,
    "params": ["lync"],
    "method": "Init"
}

Receive response

{
    "jsonrpc": "2.0",
    "result": 0,
    "id": 1455629097083
}

Control which backend device is used for call functionality. Voice for Windows is used as the default.

Note that init is applied per-connection. This means that whenever a websocket connection is opened, explicit init must be called if non-default behavior is wanted.

GetState

Send message

{
    "jsonrpc": "2.0",
    "id": 1455629097084,
    "params": [],
    "method": "GetState"
}

Receive response

{
    "jsonrpc": "2.0",
    "result": "Available",
    "id": 1455629097084
}

Returns current availability state of selected phone. If phone is not running, signed out or otherwise unavailable, Offline is returned.

CallOut

Send message

{
    "jsonrpc": "2.0",
    "id": 1455629182045,
    "params": ["+358449388834"],
    "method": "CallOut"
}

Receive response

{
    "jsonrpc": "2.0",
    "result": 0,
    "id": 1455629182045
}

Initiates a call to specified target number. Basic input validation is performed (only numeric, non-empty), but integrating client should make sure to input only valid phone numbers.

Hangup

Send message

{
    "jsonrpc": "2.0",
    "id": 1455629182021,
    "params": [],
    "method": "HangUp"
}

Receive response

{
    "jsonrpc":"2.0",
    "result":0,
    "id":1455629182021
}

Closes currently active call.

Answer

Send message

{
    "jsonrpc": "2.0",
    "id": "1455629182021",
    "params": [],
    "method": "Answer"
}

Receive response

{
    "jsonrpc":"2.0",
    "result":0,
    "id":1455629182021
}

Answers the latest ongoing unanswered incoming call.

GetActiveCalls

Send message

{
    "jsonrpc": "2.0",
    "id": 1455629182020,
    "params": [],
    "method": "GetActiveCalls"
}

Receive response

{
    "jsonrpc": "2.0",
    "result": [
        "1",
        "Outbound",
        "Calling",
        "+358449388834",
        "ID1",
        "2016-02-16 13:26:21.183"
    ],
    "id": 1455629182020
}

Returns information about currently active calls.

Notifications

Notifications are provided for incoming calls, call state changes and availability state changes. They cannot be replied to.

StateChanged

{
    "jsonrpc": "2.0",
    "method": "StateChanged",
    "params": ["Busy"]
}

Sent when phone availability state changes. Returns Enreach Core user availability, or Offline is phone is unavailable.

CallComing

{
    "jsonrpc": "2.0",
    "method": "CallComing",
    "params": [
        "ID1",
        "0505010269"
    ]
}

Sent when phone receives an incoming call.

QueueCallComing

{
    "jsonrpc": "2.0",
    "method": "QueueCallComing",
    "params": [
        "ID1",
        "aaaaaaaa-aaaa-aaaa-bbbb-cccc-ddddeeeeffff",
        "+358501231234",
        "+3581011223",
        "11111111-2222-3333-4444-5555-666677778888",
        "Master queue 1"
    ]
}

Sent when phone receives an incoming queue call. This is only in BDfW cases, these notifications are not available when working with SfB.

CallingOut

{
    "jsonrpc": "2.0",
    "method": "CallingOut",
    "params": [
        "ID1",
        "+358505010269"
    ]
}

Sent when phone starts calling out.

CallConnected

{
    "jsonrpc": "2.0",
    "method": "CallConnected",
    "params": ["ID1"]
}

Sent when call (inbound or outbound) is connected.

CallDisconnected

{
    "jsonrpc": "2.0",
    "method": "CallDisconnected",
    "params": [
        "ID1",
        "CustomData"
    ]
}

Sent when call (inbound or outbound) is disconnected.

ExtraInfo field may contain extra technical information about why call disconnected. Contents of this field is specific to underlying phone and can change in time.

Examples

Calling out

Send a call out command:

{"jsonrpc":"2.0","id":1455629182045,"params":["+358449388834"],"method":"CallOut"}

Receive a response acknowledging that the call-out request was received and is being handled:

{"jsonrpc":"2.0","result":0,"id":1455629182045}

Once the phone actually starts calling out, receive a notification:

{"jsonrpc":"2.0","method":"CallingOut","params":["ID2","+358449388834"]}

The phone state changes to busy:

{"jsonrpc":"2.0","method":"StateChanged","params":["Busy"]}

Eventually the call is answered:

{"jsonrpc":"2.0","method":"CallConnected","params":["ID2"]}

And finally disconnected (the remote party disconnects so no HangUp command)

{"jsonrpc":"2.0","method":"CallDisconnected","params":["ID2",""]}

javascript