| Table of Contents | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
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.
...
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.
...