Realtime API
- Kelli Higdon
Overview
Switchvox's Realtime API lets clients create calls and receive realtime notification of call state. The API requires authentication using the same credentials used to log into an extension's account from a web browser. The methods of the API are gated by permissions set by the PBX admin.
The API is compliant with JSON-RPC 2.0. For general information on JSON-RPC, refer to the specification. All methods may return the standard errors listed in the specification. In addition, three server error codes have been added:
-32000: Not authenticated. Login required.
-32001: Not authorized. Missing required Switchvox permission. See 'Method Permissions' below.
-32002: Session is already authenticated. This occurs when login is re-issued after a successful login.
On success, all methods return with the JSON response member 'result' set to true.
Access to the API is over a socket.io 1.0.x connection to the PBX. To connect to the server via Javascript:
sio.connect('your.pbx.host', {
'path': '/rtapi/socket.io',
'multiplex': false
});
RealTime API sessions are connection based. The 'force new connection' setting is necessary if the client will be creating multiple sessions, either sequentially or in parallel. To send a request to the server, use:
sio.emit('request', req);
where req is JSON-RPC 2.0 conforming request object specifying one of the method names described below.
Responses to requests are emitted by the server as socket.io 'response' events. The argument to the event is a JSON RPC 2.0 response object. Notifications, resulting from 'subscribe' requests, are emitted as 'notification' events. The argument is similar to a response object, but omits the 'id' field per the spec.
To listen for these socket.io events:
sio.on('response', function(res) {...});sio.on('notification', function(msg) {...});
Since responses are asynchronous, the 'id' field may be used to match a response to the corresponding request. See the JSON-RPC specification for more info on the 'id' field.
JSON-RPC Request Method and Parameter Members
The following table lists the API's method names, and the params fields for each. As mentioned in the overview, successful requests will receive a response with the result field set to true. Unsuccessful requests will result in error responses, with an error code per the JSON-RPC spec.
method: 'login'Authenticate a Switchvox account and create a new API session | |||||
|---|---|---|---|---|---|
params: | Name | Description | Required | Type | Default |
extension | The account's extension. | Yes | String | None | |
password | The account's password. | Yes | String | None | |
method: 'logout'Logout the current session | |||||
params: | Name | Description | Required | Type | Default |
none | No parameters are required for this method. Causes the socket.io connection to be dropped. If there are pending requests, the client will not receive the response, even though the request has been completed. |
|
|
| |
method: 'subscribe'Subscribe to call state notification | |||||
params: | Name | Description | Required | Type | Default |
topic | state.change.extension.line | Yes | String | None | |
targets | Limit the topics to those generated by specific entities. See below for more information. | Yes | Array of objects containing accounts: [{account: AccountObject}, ...] | None | |
method: 'unsubscribe'Unsubscribe from notifications | |||||
params: | Name | Description | Required | Type | Default |
topic | state.change.extension.line | Yes | String | None | |
targets | Limit the topics to those generated by specific entities. See below for more information. | Yes, except for 'state.change.parkingSpace'. | Array of objects containing accounts: [{account: AccountObject}, ...] | None | |
| |||||
method: 'dial'Place a call | |||||
params: | Name | Description | Required | Type | Default |
extension | Number to call, an external phone number or a Switchvox extension. | Yes | String | None | |
convergedDeviceId | Converged device id of endpoint to use for ringback or active channel selection. This is used for making calls with an Additional Phone, as opposed to the user's Main Phone. | No | ConvergedDeviceId | Session's extension | |
dialData | Caller supplied javascript object that will be returned in the state.change.extension.line event for the channel initiating the call. The object is serialized and stored as an Asterisk channel variable, and is limited to the maximum length allowed by Asterisk. Setting and recovering this value may silently fail. NOTE: This data should be considered public. Do not use it to store sensitive data. | No | Javascript object | None | |
| |||||
JSON-RPC Notification
The Realtime API 'subscribe' method provides a mechanism by which the client can receive realtime notification of call state. In the notification JSON-RPC object, the method field will be the name of the topic, and the params field contains an object with the event data. For the format of notifications, refer to the specification.
The contents of the notification object is as follows:
| ||||
|---|---|---|---|---|
event: 'state.change.extension.line' | ||||
params:
|
| Name | Description | Type |
| uniqueId | The uniqued id for this channel. | String | |
| endpoint | The endpoint object connected to this channel. | Endpoint | |
| account | The account object associate to the endpoint. | Account | |
| startTime | Creation time for this channel. | Timestamp | |
| serverTime | Time of this event. | Timestamp | |
| status | Status of the channel. One of: 'idle', 'starting', 'calling', 'onThePhone', 'ringing', 'onHold' | String | |
| remotes | An array of channels bridged with this channel. | Array of Remote | |
| dialData | If this call was created by the dial, intercom, or callVoicemail methods, and the method included a dialData parameter, the value will be returned here. | JSON object | |
| conference | If the channel is connected to MeetMe or simple conference room, this field will be included. | Conference | |
| intercom | If the channel is connected to a intercom or page extension, this field will be included. | Conference | |
| displayUrl | If an Event Trigger returns XML containing a <display_url> node, this field will be included. | String | |
| queueId | If this call is associated with a queue, this will be set to the queue account. | Account | |
| direction | One of two values: "toPbx" or "fromPbx". This is base on the initial creation of the channel. | Direction | |
Data Types
In addition to the standard JSON data types, the following types are used by the API.
Account - An object with the following fields:
serverUuid - (String) Unique Switchvox server id.
accountId - (String) Switchvox user account id. Together with serverUuid, this uniquely identifies an account across peered servers.
ConvergedDeviceId - (Integer) The id of a "converged device" meaning a user's Additional Phone.
Direction - (string) One of "fromPbx" or "toPbx". Based on initial channel creation.
Timestamp - (Integer) This is a number representing milliseconds since 1 January 1970 00:00:00 UTC.
ChannelId - (String) A unique id for a channel.
Endpoint - An object with the following fields:
tech - (String) Asterisk channel technology.
resource - (String) Associated resource identifier for the channel technology.
Remote - An object with the following fields:
endpoint - (Endpoint) The remote endpoint
number - (String) The extension
callerIdNumber - (String) Caller id number
callerIdName - (String) Caller id name.
uniqueId - (ChannelId) Unique channel id.
startTime - (Timestamp) The time of channel creation.
account - (Account) The account for the endpoint. May be undefined.
direction - (Direction) One of "fromPbx" or "toPbx".
CallerId - An object containing caller information.
name - (String) Caller id name.
number - (String) Caller id number.