https://github.com/asterisk/node-ari-client
Node.js client for ARI. This library is best effort with limited support.
https://github.com/asterisk/node-ari-client
ari asterisk javascript nodejs
Last synced: 7 months ago
JSON representation
Node.js client for ARI. This library is best effort with limited support.
- Host: GitHub
- URL: https://github.com/asterisk/node-ari-client
- Owner: asterisk
- License: other
- Created: 2014-05-28T19:06:28.000Z (over 11 years ago)
- Default Branch: master
- Last Pushed: 2024-06-03T15:36:19.000Z (over 1 year ago)
- Last Synced: 2024-10-01T18:37:59.142Z (about 1 year ago)
- Topics: ari, asterisk, javascript, nodejs
- Language: JavaScript
- Homepage:
- Size: 426 KB
- Stars: 253
- Watchers: 35
- Forks: 99
- Open Issues: 40
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
[![build status][build_image]][build]
# node-ari-client
This module contains the Node.js client library for the Asterisk REST Interface.
It builds upon the swagger-js library, providing an improved, Asterisk-specific
API over the API generated by swagger-js.
# Usage
## Installation
```bash
$ npm install ari-client
```
## API
The client exposes a connect function that can be used to connect to an instance
of ARI and to configure a client with all available resources and operations.
Callbacks:
```javascript
var client = require('ari-client');
client.connect(url, username, password, function (err, ari) {})
```
Promises:
```javascript
var client = require('ari-client');
client.connect(url, username, password)
.then(function (ari) {})
.catch(function (err) {});
```
Upon connecting, a callback will be called passing a reference to a client with
all available resources attached.
```
ari.bridges, ari.channels, ari.endpoints...
```
Those properties expose operations that can be performed for that given resource.
Callbacks:
```javascript
ari.bridges.list(function (err, bridges) {});
ari.bridges.get({bridgeId: 'uniqueid'}, function (err, bridge) {});
```
Promises:
```javascript
ari.bridges.list()
.then(function (bridges) {})
.catch(function (err) {});
ari.bridges.get({bridgeId: 'uniqueid'})
.then(function (bridge) {})
.catch(function (err) {});
```
Operations that return a resource or a list of resources expose the same operations tied to that given instance.
```javascript
bridge.addChannel({channel: 'uniqueid'});
```
Note that the bridge id was not required since the operation was called from a resource instance. The above operation is equivalent to the following:
```javascript
ari.bridges.addChannel({bridgeId: 'uniqueid', channel: 'uniqueid'});
```
The client also exposes functions to create new resources.
```
ari.Bridge(), ari.Channel(), ari.Playback(), ari.LiveRecording()
```
The instance returned by these functions can then be used to call a create operations in ARI.
Callbacks:
```javascript
var bridge = ari.Bridge();
bridge.create(function (err, bridge) {});
```
Promises:
```javascript
var bridge = ari.Bridge();
bridge.create()
.then(function (bridge) {})
.catch(function (err) {});
```
Note that the create operation returns an updated copy of the bridge after creation.
Using this method of resource creation, it is possible to register event listeners for a resource before it is created in ARI.
Callbacks:
```javascript
var channel = ari.Channel();
channel.on('StasisStart', function (event, channel) {});
channel.on('ChannelDtmfReceived', function (event, channel) {});
channel.originate(
{endpoint: 'PJSIP/1000', app: 'application', appArgs: 'dialed'},
function (err, channel) {}
);
```
Promises:
```javascript
var channel = ari.Channel();
channel.on('StasisStart', function (event, channel) {});
channel.on('ChannelDtmfReceived', function (event, channel) {});
channel.originate({endpoint: 'PJSIP/1000', app: 'application', appArgs: 'dialed'})
.then(function (channel) {})
.catch(function (err) {});
```
Some create operations require an instance be passed in for this to work.
Callbacks:
```javascript
var playback = ari.Playback();
channel.play({media: 'sound:hello-world'}, playback, function (err, playback) {});
```
Promises:
```javascript
var playback = ari.Playback();
channel.play({media: 'sound:hello-world'}, playback)
.then(function (playback) {})
.catch(function (err) {});
```
If you are using the client directly to call a create operation instead of using an instance, you will have to pass the appropriate ids as part of the options to the create operation.
Callbacks:
```javascript
var playback = ari.Playback();
ari.channels.play({
media: 'sound:hello-world',
channelId: channel.id,
playbackId: playback.id
}, function (err, playback) {});
```
Promises:
```javascript
var playback = ari.Playback();
ari.channels.play({
media: 'sound:hello-world',
channelId: channel.id,
playbackId: playback.id
}).then(function (playback) {}).catch(function (err) {});
```
### Operations
The following operations are defined:
#### applications
##### filter
Filter application events types.
Callbacks:
```javascript
ari.applications.filter(
{applicationName: val},
function (err, application) {}
);
```
Promises:
```javascript
ari.applications.filter({
applicationName: val
})
.then(function (application) {})
.catch(function (err) {});
```
###### Available Parameters
- applicationName (string) - Application's name
- filter (object) - Specify which event types to allow/disallow
##### get
Get details of an application.
Callbacks:
```javascript
ari.applications.get(
{applicationName: val},
function (err, application) {}
);
```
Promises:
```javascript
ari.applications.get({
applicationName: val
})
.then(function (application) {})
.catch(function (err) {});
```
###### Available Parameters
- applicationName (string) - Application's name
##### list
List all applications.
Callbacks:
```javascript
ari.applications.list(
function (err, applications) {}
);
```
Promises:
```javascript
ari.applications.list()
.then(function (applications) {})
.catch(function (err) {});
```
##### subscribe
Subscribe an application to a event source.
Callbacks:
```javascript
ari.applications.subscribe(
{applicationName: val, eventSource: val},
function (err, application) {}
);
```
Promises:
```javascript
ari.applications.subscribe({
applicationName: val,
eventSource: val
})
.then(function (application) {})
.catch(function (err) {});
```
###### Available Parameters
- applicationName (string) - Application's name
- eventSource (string) - URI for event source (channel:{channelId}, bridge:{bridgeId}, endpoint:{tech}[/{resource}], deviceState:{deviceName}
##### unsubscribe
Unsubscribe an application from an event source.
Callbacks:
```javascript
ari.applications.unsubscribe(
{applicationName: val, eventSource: val},
function (err, application) {}
);
```
Promises:
```javascript
ari.applications.unsubscribe({
applicationName: val,
eventSource: val
})
.then(function (application) {})
.catch(function (err) {});
```
###### Available Parameters
- applicationName (string) - Application's name
- eventSource (string) - URI for event source (channel:{channelId}, bridge:{bridgeId}, endpoint:{tech}[/{resource}], deviceState:{deviceName}
#### asterisk
##### addLog
Adds a log channel.
Callbacks:
```javascript
ari.asterisk.addLog(
{configuration: val, logChannelName: val},
function (err) {}
);
```
Promises:
```javascript
ari.asterisk.addLog({
configuration: val,
logChannelName: val
})
.then(function () {})
.catch(function (err) {});
```
###### Available Parameters
- configuration (string) - levels of the log channel
- logChannelName (string) - The log channel to add
##### deleteLog
Deletes a log channel.
Callbacks:
```javascript
ari.asterisk.deleteLog(
{logChannelName: val},
function (err) {}
);
```
Promises:
```javascript
ari.asterisk.deleteLog({
logChannelName: val
})
.then(function () {})
.catch(function (err) {});
```
###### Available Parameters
- logChannelName (string) - Log channels name
##### deleteObject
Delete a dynamic configuration object.
Callbacks:
```javascript
ari.asterisk.deleteObject(
{configClass: val, id: val, objectType: val},
function (err) {}
);
```
Promises:
```javascript
ari.asterisk.deleteObject({
configClass: val,
id: val,
objectType: val
})
.then(function () {})
.catch(function (err) {});
```
###### Available Parameters
- configClass (string) - The configuration class containing dynamic configuration objects.
- id (string) - The unique identifier of the object to delete.
- objectType (string) - The type of configuration object to delete.
##### getGlobalVar
Get the value of a global variable.
Callbacks:
```javascript
ari.asterisk.getGlobalVar(
{variable: val},
function (err, variable) {}
);
```
Promises:
```javascript
ari.asterisk.getGlobalVar({
variable: val
})
.then(function (variable) {})
.catch(function (err) {});
```
###### Available Parameters
- variable (string) - The variable to get
##### getInfo
Gets Asterisk system information.
Callbacks:
```javascript
ari.asterisk.getInfo(
function (err, asteriskinfo) {}
);
```
Promises:
```javascript
ari.asterisk.getInfo()
.then(function (asteriskinfo) {})
.catch(function (err) {});
```
###### Available Parameters
- only (string) - Filter information returned
##### getModule
Get Asterisk module information.
Callbacks:
```javascript
ari.asterisk.getModule(
{moduleName: val},
function (err, module) {}
);
```
Promises:
```javascript
ari.asterisk.getModule({
moduleName: val
})
.then(function (module) {})
.catch(function (err) {});
```
###### Available Parameters
- moduleName (string) - Module's name
##### getObject
Retrieve a dynamic configuration object.
Callbacks:
```javascript
ari.asterisk.getObject(
{configClass: val, id: val, objectType: val},
function (err, configtuples) {}
);
```
Promises:
```javascript
ari.asterisk.getObject({
configClass: val,
id: val,
objectType: val
})
.then(function (configtuples) {})
.catch(function (err) {});
```
###### Available Parameters
- configClass (string) - The configuration class containing dynamic configuration objects.
- id (string) - The unique identifier of the object to retrieve.
- objectType (string) - The type of configuration object to retrieve.
##### listLogChannels
Gets Asterisk log channel information.
Callbacks:
```javascript
ari.asterisk.listLogChannels(
function (err, logchannels) {}
);
```
Promises:
```javascript
ari.asterisk.listLogChannels()
.then(function (logchannels) {})
.catch(function (err) {});
```
##### listModules
List Asterisk modules.
Callbacks:
```javascript
ari.asterisk.listModules(
function (err, modules) {}
);
```
Promises:
```javascript
ari.asterisk.listModules()
.then(function (modules) {})
.catch(function (err) {});
```
##### loadModule
Load an Asterisk module.
Callbacks:
```javascript
ari.asterisk.loadModule(
{moduleName: val},
function (err) {}
);
```
Promises:
```javascript
ari.asterisk.loadModule({
moduleName: val
})
.then(function () {})
.catch(function (err) {});
```
###### Available Parameters
- moduleName (string) - Module's name
##### ping
Response pong message.
Callbacks:
```javascript
ari.asterisk.ping(
function (err, asteriskping) {}
);
```
Promises:
```javascript
ari.asterisk.ping()
.then(function (asteriskping) {})
.catch(function (err) {});
```
##### reloadModule
Reload an Asterisk module.
Callbacks:
```javascript
ari.asterisk.reloadModule(
{moduleName: val},
function (err) {}
);
```
Promises:
```javascript
ari.asterisk.reloadModule({
moduleName: val
})
.then(function () {})
.catch(function (err) {});
```
###### Available Parameters
- moduleName (string) - Module's name
##### rotateLog
Rotates a log channel.
Callbacks:
```javascript
ari.asterisk.rotateLog(
{logChannelName: val},
function (err) {}
);
```
Promises:
```javascript
ari.asterisk.rotateLog({
logChannelName: val
})
.then(function () {})
.catch(function (err) {});
```
###### Available Parameters
- logChannelName (string) - Log channel's name
##### setGlobalVar
Set the value of a global variable.
Callbacks:
```javascript
ari.asterisk.setGlobalVar(
{variable: val},
function (err) {}
);
```
Promises:
```javascript
ari.asterisk.setGlobalVar({
variable: val
})
.then(function () {})
.catch(function (err) {});
```
###### Available Parameters
- value (string) - The value to set the variable to
- variable (string) - The variable to set
##### unloadModule
Unload an Asterisk module.
Callbacks:
```javascript
ari.asterisk.unloadModule(
{moduleName: val},
function (err) {}
);
```
Promises:
```javascript
ari.asterisk.unloadModule({
moduleName: val
})
.then(function () {})
.catch(function (err) {});
```
###### Available Parameters
- moduleName (string) - Module's name
##### updateObject
Create or update a dynamic configuration object.
Callbacks:
```javascript
ari.asterisk.updateObject(
{configClass: val, id: val, objectType: val},
function (err, configtuples) {}
);
```
Promises:
```javascript
ari.asterisk.updateObject({
configClass: val,
id: val,
objectType: val
})
.then(function (configtuples) {})
.catch(function (err) {});
```
###### Available Parameters
- configClass (string) - The configuration class containing dynamic configuration objects.
- fields (containers) - The body object should have a value that is a list of ConfigTuples, which provide the fields to update. Ex. [ { "attribute": "directmedia", "value": "false" } ]
- id (string) - The unique identifier of the object to create or update.
- objectType (string) - The type of configuration object to create or update.
#### bridges
##### addChannel
Add a channel to a bridge.
Callbacks:
```javascript
ari.bridges.addChannel(
{bridgeId: val, channel: val},
function (err) {}
);
```
Promises:
```javascript
ari.bridges.addChannel({
bridgeId: val,
channel: val
})
.then(function () {})
.catch(function (err) {});
```
###### Available Parameters
- absorbDTMF (boolean) - Absorb DTMF coming from this channel, preventing it to pass through to the bridge
- bridgeId (string) - Bridge's id
- channel (string) - Ids of channels to add to bridge
- mute (boolean) - Mute audio from this channel, preventing it to pass through to the bridge
- role (string) - Channel's role in the bridge
##### clearVideoSource
Removes any explicit video source in a multi-party mixing bridge. This operation has no effect on bridges with two or fewer participants. When no explicit video source is set, talk detection will be used to determine the active video stream.
Callbacks:
```javascript
ari.bridges.clearVideoSource(
{bridgeId: val},
function (err) {}
);
```
Promises:
```javascript
ari.bridges.clearVideoSource({
bridgeId: val
})
.then(function () {})
.catch(function (err) {});
```
###### Available Parameters
- bridgeId (string) - Bridge's id
##### create
Create a new bridge.
Callbacks:
```javascript
ari.bridges.create(
function (err, bridge) {}
);
```
Promises:
```javascript
ari.bridges.create()
.then(function (bridge) {})
.catch(function (err) {});
```
###### Available Parameters
- bridgeId (string) - Unique ID to give to the bridge being created.
- name (string) - Name to give to the bridge being created.
- type (string) - Comma separated list of bridge type attributes (mixing, holding, dtmf_events, proxy_media, video_sfu).
##### createWithId
Create a new bridge or updates an existing one.
Callbacks:
```javascript
ari.bridges.createWithId(
{bridgeId: val},
function (err, bridge) {}
);
```
Promises:
```javascript
ari.bridges.createWithId({
bridgeId: val
})
.then(function (bridge) {})
.catch(function (err) {});
```
###### Available Parameters
- bridgeId (string) - Unique ID to give to the bridge being created.
- name (string) - Set the name of the bridge.
- type (string) - Comma separated list of bridge type attributes (mixing, holding, dtmf_events, proxy_media, video_sfu) to set.
##### destroy
Shut down a bridge.
Callbacks:
```javascript
ari.bridges.destroy(
{bridgeId: val},
function (err) {}
);
```
Promises:
```javascript
ari.bridges.destroy({
bridgeId: val
})
.then(function () {})
.catch(function (err) {});
```
###### Available Parameters
- bridgeId (string) - Bridge's id
##### get
Get bridge details.
Callbacks:
```javascript
ari.bridges.get(
{bridgeId: val},
function (err, bridge) {}
);
```
Promises:
```javascript
ari.bridges.get({
bridgeId: val
})
.then(function (bridge) {})
.catch(function (err) {});
```
###### Available Parameters
- bridgeId (string) - Bridge's id
##### list
List all active bridges in Asterisk.
Callbacks:
```javascript
ari.bridges.list(
function (err, bridges) {}
);
```
Promises:
```javascript
ari.bridges.list()
.then(function (bridges) {})
.catch(function (err) {});
```
##### play
Start playback of media on a bridge.
Callbacks:
```javascript
ari.bridges.play(
{bridgeId: val, media: val},
function (err, playback) {}
);
```
Promises:
```javascript
ari.bridges.play({
bridgeId: val,
media: val
})
.then(function (playback) {})
.catch(function (err) {});
```
###### Available Parameters
- bridgeId (string) - Bridge's id
- lang (string) - For sounds, selects language for sound.
- media (string) - Media URIs to play.
- offsetms (int) - Number of milliseconds to skip before playing. Only applies to the first URI if multiple media URIs are specified.
- playbackId (string) - Playback Id.
- skipms (int) - Number of milliseconds to skip for forward/reverse operations.
##### playWithId
Start playback of media on a bridge.
Callbacks:
```javascript
ari.bridges.playWithId(
{bridgeId: val, media: val, playbackId: val},
function (err, playback) {}
);
```
Promises:
```javascript
ari.bridges.playWithId({
bridgeId: val,
media: val,
playbackId: val
})
.then(function (playback) {})
.catch(function (err) {});
```
###### Available Parameters
- bridgeId (string) - Bridge's id
- lang (string) - For sounds, selects language for sound.
- media (string) - Media URIs to play.
- offsetms (int) - Number of milliseconds to skip before playing. Only applies to the first URI if multiple media URIs are specified.
- playbackId (string) - Playback ID.
- skipms (int) - Number of milliseconds to skip for forward/reverse operations.
##### record
Start a recording.
Callbacks:
```javascript
ari.bridges.record(
{bridgeId: val, format: val, name: val},
function (err, liverecording) {}
);
```
Promises:
```javascript
ari.bridges.record({
bridgeId: val,
format: val,
name: val
})
.then(function (liverecording) {})
.catch(function (err) {});
```
###### Available Parameters
- beep (boolean) - Play beep when recording begins
- bridgeId (string) - Bridge's id
- format (string) - Format to encode audio in
- ifExists (string) - Action to take if a recording with the same name already exists.
- maxDurationSeconds (int) - Maximum duration of the recording, in seconds. 0 for no limit.
- maxSilenceSeconds (int) - Maximum duration of silence, in seconds. 0 for no limit.
- name (string) - Recording's filename
- terminateOn (string) - DTMF input to terminate recording.
##### removeChannel
Remove a channel from a bridge.
Callbacks:
```javascript
ari.bridges.removeChannel(
{bridgeId: val, channel: val},
function (err) {}
);
```
Promises:
```javascript
ari.bridges.removeChannel({
bridgeId: val,
channel: val
})
.then(function () {})
.catch(function (err) {});
```
###### Available Parameters
- bridgeId (string) - Bridge's id
- channel (string) - Ids of channels to remove from bridge
##### setVideoSource
Set a channel as the video source in a multi-party mixing bridge. This operation has no effect on bridges with two or fewer participants.
Callbacks:
```javascript
ari.bridges.setVideoSource(
{bridgeId: val, channelId: val},
function (err) {}
);
```
Promises:
```javascript
ari.bridges.setVideoSource({
bridgeId: val,
channelId: val
})
.then(function () {})
.catch(function (err) {});
```
###### Available Parameters
- bridgeId (string) - Bridge's id
- channelId (string) - Channel's id
##### startMoh
Play music on hold to a bridge or change the MOH class that is playing.
Callbacks:
```javascript
ari.bridges.startMoh(
{bridgeId: val},
function (err) {}
);
```
Promises:
```javascript
ari.bridges.startMoh({
bridgeId: val
})
.then(function () {})
.catch(function (err) {});
```
###### Available Parameters
- bridgeId (string) - Bridge's id
- mohClass (string) - Channel's id
##### stopMoh
Stop playing music on hold to a bridge.
Callbacks:
```javascript
ari.bridges.stopMoh(
{bridgeId: val},
function (err) {}
);
```
Promises:
```javascript
ari.bridges.stopMoh({
bridgeId: val
})
.then(function () {})
.catch(function (err) {});
```
###### Available Parameters
- bridgeId (string) - Bridge's id
#### channels
##### answer
Answer a channel.
Callbacks:
```javascript
ari.channels.answer(
{channelId: val},
function (err) {}
);
```
Promises:
```javascript
ari.channels.answer({
channelId: val
})
.then(function () {})
.catch(function (err) {});
```
###### Available Parameters
- channelId (string) - Channel's id
##### continueInDialplan
Exit application; continue execution in the dialplan.
Callbacks:
```javascript
ari.channels.continueInDialplan(
{channelId: val},
function (err) {}
);
```
Promises:
```javascript
ari.channels.continueInDialplan({
channelId: val
})
.then(function () {})
.catch(function (err) {});
```
###### Available Parameters
- channelId (string) - Channel's id
- context (string) - The context to continue to.
- extension (string) - The extension to continue to.
- label (string) - The label to continue to - will supersede 'priority' if both are provided.
- priority (int) - The priority to continue to.
##### create
Create channel.
Callbacks:
```javascript
ari.channels.create(
{app: val, endpoint: val},
function (err, channel) {}
);
```
Promises:
```javascript
ari.channels.create({
app: val,
endpoint: val
})
.then(function (channel) {})
.catch(function (err) {});
```
###### Available Parameters
- app (string) - Stasis Application to place channel into
- appArgs (string) - The application arguments to pass to the Stasis application provided by 'app'. Mutually exclusive with 'context', 'extension', 'priority', and 'label'.
- channelId (string) - The unique id to assign the channel on creation.
- endpoint (string) - Endpoint for channel communication
- formats (string) - The format name capability list to use if originator is not specified. Ex. "ulaw,slin16". Format names can be found with "core show codecs".
- originator (string) - Unique ID of the calling channel
- otherChannelId (string) - The unique id to assign the second channel when using local channels.
##### dial
Dial a created channel.
Callbacks:
```javascript
ari.channels.dial(
{channelId: val},
function (err) {}
);
```
Promises:
```javascript
ari.channels.dial({
channelId: val
})
.then(function () {})
.catch(function (err) {});
```
###### Available Parameters
- caller (string) - Channel ID of caller
- channelId (string) - Channel's id
- timeout (int) - Dial timeout
##### externalMedia
Start an External Media session.
Callbacks:
```javascript
ari.channels.externalMedia(
{app: val, external_host: val, format: val},
function (err, channel) {}
);
```
Promises:
```javascript
ari.channels.externalMedia({
app: val,
external_host: val,
format: val
})
.then(function (channel) {})
.catch(function (err) {});
```
###### Available Parameters
- app (string) - Stasis Application to place channel into
- channelId (string) - The unique id to assign the channel on creation.
- connection_type (string) - Connection type (client/server)
- direction (string) - External media direction
- encapsulation (string) - Payload encapsulation protocol
- external_host (string) - Hostname/ip:port of external host
- format (string) - Format to encode audio in
- transport (string) - Transport protocol
- variables (containers) - The "variables" key in the body object holds variable key/value pairs to set on the channel on creation. Other keys in the body object are interpreted as query parameters. Ex. { "endpoint": "SIP/Alice", "variables": { "CALLERID(name)": "Alice" } }
##### get
Channel details.
Callbacks:
```javascript
ari.channels.get(
{channelId: val},
function (err, channel) {}
);
```
Promises:
```javascript
ari.channels.get({
channelId: val
})
.then(function (channel) {})
.catch(function (err) {});
```
###### Available Parameters
- channelId (string) - Channel's id
##### getChannelVar
Get the value of a channel variable or function.
Callbacks:
```javascript
ari.channels.getChannelVar(
{channelId: val, variable: val},
function (err, variable) {}
);
```
Promises:
```javascript
ari.channels.getChannelVar({
channelId: val,
variable: val
})
.then(function (variable) {})
.catch(function (err) {});
```
###### Available Parameters
- channelId (string) - Channel's id
- variable (string) - The channel variable or function to get
##### hangup
Delete (i.e. hangup) a channel.
Callbacks:
```javascript
ari.channels.hangup(
{channelId: val},
function (err) {}
);
```
Promises:
```javascript
ari.channels.hangup({
channelId: val
})
.then(function () {})
.catch(function (err) {});
```
###### Available Parameters
- channelId (string) - Channel's id
- reason (string) - Reason for hanging up the channel
##### hold
Hold a channel.
Callbacks:
```javascript
ari.channels.hold(
{channelId: val},
function (err) {}
);
```
Promises:
```javascript
ari.channels.hold({
channelId: val
})
.then(function () {})
.catch(function (err) {});
```
###### Available Parameters
- channelId (string) - Channel's id
##### list
List all active channels in Asterisk.
Callbacks:
```javascript
ari.channels.list(
function (err, channels) {}
);
```
Promises:
```javascript
ari.channels.list()
.then(function (channels) {})
.catch(function (err) {});
```
##### move
Move the channel from one Stasis application to another.
Callbacks:
```javascript
ari.channels.move(
{app: val, channelId: val},
function (err) {}
);
```
Promises:
```javascript
ari.channels.move({
app: val,
channelId: val
})
.then(function () {})
.catch(function (err) {});
```
###### Available Parameters
- app (string) - The channel will be passed to this Stasis application.
- appArgs (string) - The application arguments to pass to the Stasis application provided by 'app'.
- channelId (string) - Channel's id
##### mute
Mute a channel.
Callbacks:
```javascript
ari.channels.mute(
{channelId: val},
function (err) {}
);
```
Promises:
```javascript
ari.channels.mute({
channelId: val
})
.then(function () {})
.catch(function (err) {});
```
###### Available Parameters
- channelId (string) - Channel's id
- direction (string) - Direction in which to mute audio
##### originate
Create a new channel (originate).
Callbacks:
```javascript
ari.channels.originate(
{endpoint: val},
function (err, channel) {}
);
```
Promises:
```javascript
ari.channels.originate({
endpoint: val
})
.then(function (channel) {})
.catch(function (err) {});
```
###### Available Parameters
- app (string) - The application that is subscribed to the originated channel. When the channel is answered, it will be passed to this Stasis application. Mutually exclusive with 'context', 'extension', 'priority', and 'label'.
- appArgs (string) - The application arguments to pass to the Stasis application provided by 'app'. Mutually exclusive with 'context', 'extension', 'priority', and 'label'.
- callerId (string) - CallerID to use when dialing the endpoint or extension.
- channelId (string) - The unique id to assign the channel on creation.
- context (string) - The context to dial after the endpoint answers. If omitted, uses 'default'. Mutually exclusive with 'app'.
- endpoint (string) - Endpoint to call.
- extension (string) - The extension to dial after the endpoint answers. Mutually exclusive with 'app'.
- formats (string) - The format name capability list to use if originator is not specified. Ex. "ulaw,slin16". Format names can be found with "core show codecs".
- label (string) - The label to dial after the endpoint answers. Will supersede 'priority' if provided. Mutually exclusive with 'app'.
- originator (string) - The unique id of the channel which is originating this one.
- otherChannelId (string) - The unique id to assign the second channel when using local channels.
- priority (long) - The priority to dial after the endpoint answers. If omitted, uses 1. Mutually exclusive with 'app'.
- timeout (int) - Timeout (in seconds) before giving up dialing, or -1 for no timeout.
- variables (containers) - The "variables" key in the body object holds variable key/value pairs to set on the channel on creation. Other keys in the body object are interpreted as query parameters. Ex. { "endpoint": "SIP/Alice", "variables": { "CALLERID(name)": "Alice" } }
##### originateWithId
Create a new channel (originate with id).
Callbacks:
```javascript
ari.channels.originateWithId(
{channelId: val, endpoint: val},
function (err, channel) {}
);
```
Promises:
```javascript
ari.channels.originateWithId({
channelId: val,
endpoint: val
})
.then(function (channel) {})
.catch(function (err) {});
```
###### Available Parameters
- app (string) - The application that is subscribed to the originated channel. When the channel is answered, it will be passed to this Stasis application. Mutually exclusive with 'context', 'extension', 'priority', and 'label'.
- appArgs (string) - The application arguments to pass to the Stasis application provided by 'app'. Mutually exclusive with 'context', 'extension', 'priority', and 'label'.
- callerId (string) - CallerID to use when dialing the endpoint or extension.
- channelId (string) - The unique id to assign the channel on creation.
- context (string) - The context to dial after the endpoint answers. If omitted, uses 'default'. Mutually exclusive with 'app'.
- endpoint (string) - Endpoint to call.
- extension (string) - The extension to dial after the endpoint answers. Mutually exclusive with 'app'.
- formats (string) - The format name capability list to use if originator is not specified. Ex. "ulaw,slin16". Format names can be found with "core show codecs".
- label (string) - The label to dial after the endpoint answers. Will supersede 'priority' if provided. Mutually exclusive with 'app'.
- originator (string) - The unique id of the channel which is originating this one.
- otherChannelId (string) - The unique id to assign the second channel when using local channels.
- priority (long) - The priority to dial after the endpoint answers. If omitted, uses 1. Mutually exclusive with 'app'.
- timeout (int) - Timeout (in seconds) before giving up dialing, or -1 for no timeout.
- variables (containers) - The "variables" key in the body object holds variable key/value pairs to set on the channel on creation. Other keys in the body object are interpreted as query parameters. Ex. { "endpoint": "SIP/Alice", "variables": { "CALLERID(name)": "Alice" } }
##### play
Start playback of media.
Callbacks:
```javascript
ari.channels.play(
{channelId: val, media: val},
function (err, playback) {}
);
```
Promises:
```javascript
ari.channels.play({
channelId: val,
media: val
})
.then(function (playback) {})
.catch(function (err) {});
```
###### Available Parameters
- channelId (string) - Channel's id
- lang (string) - For sounds, selects language for sound.
- media (string) - Media URIs to play.
- offsetms (int) - Number of milliseconds to skip before playing. Only applies to the first URI if multiple media URIs are specified.
- playbackId (string) - Playback ID.
- skipms (int) - Number of milliseconds to skip for forward/reverse operations.
##### playWithId
Start playback of media and specify the playbackId.
Callbacks:
```javascript
ari.channels.playWithId(
{channelId: val, media: val, playbackId: val},
function (err, playback) {}
);
```
Promises:
```javascript
ari.channels.playWithId({
channelId: val,
media: val,
playbackId: val
})
.then(function (playback) {})
.catch(function (err) {});
```
###### Available Parameters
- channelId (string) - Channel's id
- lang (string) - For sounds, selects language for sound.
- media (string) - Media URIs to play.
- offsetms (int) - Number of milliseconds to skip before playing. Only applies to the first URI if multiple media URIs are specified.
- playbackId (string) - Playback ID.
- skipms (int) - Number of milliseconds to skip for forward/reverse operations.
##### record
Start a recording.
Callbacks:
```javascript
ari.channels.record(
{channelId: val, format: val, name: val},
function (err, liverecording) {}
);
```
Promises:
```javascript
ari.channels.record({
channelId: val,
format: val,
name: val
})
.then(function (liverecording) {})
.catch(function (err) {});
```
###### Available Parameters
- beep (boolean) - Play beep when recording begins
- channelId (string) - Channel's id
- format (string) - Format to encode audio in
- ifExists (string) - Action to take if a recording with the same name already exists.
- maxDurationSeconds (int) - Maximum duration of the recording, in seconds. 0 for no limit
- maxSilenceSeconds (int) - Maximum duration of silence, in seconds. 0 for no limit
- name (string) - Recording's filename
- terminateOn (string) - DTMF input to terminate recording
##### redirect
Redirect the channel to a different location.
Callbacks:
```javascript
ari.channels.redirect(
{channelId: val, endpoint: val},
function (err) {}
);
```
Promises:
```javascript
ari.channels.redirect({
channelId: val,
endpoint: val
})
.then(function () {})
.catch(function (err) {});
```
###### Available Parameters
- channelId (string) - Channel's id
- endpoint (string) - The endpoint to redirect the channel to
##### ring
Indicate ringing to a channel.
Callbacks:
```javascript
ari.channels.ring(
{channelId: val},
function (err) {}
);
```
Promises:
```javascript
ari.channels.ring({
channelId: val
})
.then(function () {})
.catch(function (err) {});
```
###### Available Parameters
- channelId (string) - Channel's id
##### ringStop
Stop ringing indication on a channel if locally generated.
Callbacks:
```javascript
ari.channels.ringStop(
{channelId: val},
function (err) {}
);
```
Promises:
```javascript
ari.channels.ringStop({
channelId: val
})
.then(function () {})
.catch(function (err) {});
```
###### Available Parameters
- channelId (string) - Channel's id
##### rtpstatistics
RTP stats on a channel.
Callbacks:
```javascript
ari.channels.rtpstatistics(
{channelId: val},
function (err, rtpstat) {}
);
```
Promises:
```javascript
ari.channels.rtpstatistics({
channelId: val
})
.then(function (rtpstat) {})
.catch(function (err) {});
```
###### Available Parameters
- channelId (string) - Channel's id
##### sendDTMF
Send provided DTMF to a given channel.
Callbacks:
```javascript
ari.channels.sendDTMF(
{channelId: val},
function (err) {}
);
```
Promises:
```javascript
ari.channels.sendDTMF({
channelId: val
})
.then(function () {})
.catch(function (err) {});
```
###### Available Parameters
- after (int) - Amount of time to wait after DTMF digits (specified in milliseconds) end.
- before (int) - Amount of time to wait before DTMF digits (specified in milliseconds) start.
- between (int) - Amount of time in between DTMF digits (specified in milliseconds).
- channelId (string) - Channel's id
- dtmf (string) - DTMF To send.
- duration (int) - Length of each DTMF digit (specified in milliseconds).
##### setChannelVar
Set the value of a channel variable or function.
Callbacks:
```javascript
ari.channels.setChannelVar(
{channelId: val, variable: val},
function (err) {}
);
```
Promises:
```javascript
ari.channels.setChannelVar({
channelId: val,
variable: val
})
.then(function () {})
.catch(function (err) {});
```
###### Available Parameters
- channelId (string) - Channel's id
- value (string) - The value to set the variable to
- variable (string) - The channel variable or function to set
##### snoopChannel
Start snooping.
Callbacks:
```javascript
ari.channels.snoopChannel(
{app: val, channelId: val},
function (err, channel) {}
);
```
Promises:
```javascript
ari.channels.snoopChannel({
app: val,
channelId: val
})
.then(function (channel) {})
.catch(function (err) {});
```
###### Available Parameters
- app (string) - Application the snooping channel is placed into
- appArgs (string) - The application arguments to pass to the Stasis application
- channelId (string) - Channel's id
- snoopId (string) - Unique ID to assign to snooping channel
- spy (string) - Direction of audio to spy on
- whisper (string) - Direction of audio to whisper into
##### snoopChannelWithId
Start snooping.
Callbacks:
```javascript
ari.channels.snoopChannelWithId(
{app: val, channelId: val, snoopId: val},
function (err, channel) {}
);
```
Promises:
```javascript
ari.channels.snoopChannelWithId({
app: val,
channelId: val,
snoopId: val
})
.then(function (channel) {})
.catch(function (err) {});
```
###### Available Parameters
- app (string) - Application the snooping channel is placed into
- appArgs (string) - The application arguments to pass to the Stasis application
- channelId (string) - Channel's id
- snoopId (string) - Unique ID to assign to snooping channel
- spy (string) - Direction of audio to spy on
- whisper (string) - Direction of audio to whisper into
##### startMoh
Play music on hold to a channel.
Callbacks:
```javascript
ari.channels.startMoh(
{channelId: val},
function (err) {}
);
```
Promises:
```javascript
ari.channels.startMoh({
channelId: val
})
.then(function () {})
.catch(function (err) {});
```
###### Available Parameters
- channelId (string) - Channel's id
- mohClass (string) - Music on hold class to use
##### startSilence
Play silence to a channel.
Callbacks:
```javascript
ari.channels.startSilence(
{channelId: val},
function (err) {}
);
```
Promises:
```javascript
ari.channels.startSilence({
channelId: val
})
.then(function () {})
.catch(function (err) {});
```
###### Available Parameters
- channelId (string) - Channel's id
##### stopMoh
Stop playing music on hold to a channel.
Callbacks:
```javascript
ari.channels.stopMoh(
{channelId: val},
function (err) {}
);
```
Promises:
```javascript
ari.channels.stopMoh({
channelId: val
})
.then(function () {})
.catch(function (err) {});
```
###### Available Parameters
- channelId (string) - Channel's id
##### stopSilence
Stop playing silence to a channel.
Callbacks:
```javascript
ari.channels.stopSilence(
{channelId: val},
function (err) {}
);
```
Promises:
```javascript
ari.channels.stopSilence({
channelId: val
})
.then(function () {})
.catch(function (err) {});
```
###### Available Parameters
- channelId (string) - Channel's id
##### unhold
Remove a channel from hold.
Callbacks:
```javascript
ari.channels.unhold(
{channelId: val},
function (err) {}
);
```
Promises:
```javascript
ari.channels.unhold({
channelId: val
})
.then(function () {})
.catch(function (err) {});
```
###### Available Parameters
- channelId (string) - Channel's id
##### unmute
Unmute a channel.
Callbacks:
```javascript
ari.channels.unmute(
{channelId: val},
function (err) {}
);
```
Promises:
```javascript
ari.channels.unmute({
channelId: val
})
.then(function () {})
.catch(function (err) {});
```
###### Available Parameters
- channelId (string) - Channel's id
- direction (string) - Direction in which to unmute audio
#### deviceStates
##### delete
Destroy a device-state controlled by ARI.
Callbacks:
```javascript
ari.deviceStates.delete(
{deviceName: val},
function (err) {}
);
```
Promises:
```javascript
ari.deviceStates.delete({
deviceName: val
})
.then(function () {})
.catch(function (err) {});
```
###### Available Parameters
- deviceName (string) - Name of the device
##### get
Retrieve the current state of a device.
Callbacks:
```javascript
ari.deviceStates.get(
{deviceName: val},
function (err, devicestate) {}
);
```
Promises:
```javascript
ari.deviceStates.get({
deviceName: val
})
.then(function (devicestate) {})
.catch(function (err) {});
```
###### Available Parameters
- deviceName (string) - Name of the device
##### list
List all ARI controlled device states.
Callbacks:
```javascript
ari.deviceStates.list(
function (err, devicestates) {}
);
```
Promises:
```javascript
ari.deviceStates.list()
.then(function (devicestates) {})
.catch(function (err) {});
```
##### update
Change the state of a device controlled by ARI. (Note - implicitly creates the device state).
Callbacks:
```javascript
ari.deviceStates.update(
{deviceName: val, deviceState: val},
function (err) {}
);
```
Promises:
```javascript
ari.deviceStates.update({
deviceName: val,
deviceState: val
})
.then(function () {})
.catch(function (err) {});
```
###### Available Parameters
- deviceName (string) - Name of the device
- deviceState (string) - Device state value
#### endpoints
##### get
Details for an endpoint.
Callbacks:
```javascript
ari.endpoints.get(
function (err, endpoint) {}
);
```
Promises:
```javascript
ari.endpoints.get()
.then(function (endpoint) {})
.catch(function (err) {});
```
###### Available Parameters
- resource (string) - ID of the endpoint
- tech (string) - Technology of the endpoint
##### list
List all endpoints.
Callbacks:
```javascript
ari.endpoints.list(
function (err, endpoints) {}
);
```
Promises:
```javascript
ari.endpoints.list()
.then(function (endpoints) {})
.catch(function (err) {});
```
##### listByTech
List available endoints for a given endpoint technology.
Callbacks:
```javascript
ari.endpoints.listByTech(
function (err, endpoints) {}
);
```
Promises:
```javascript
ari.endpoints.listByTech()
.then(function (endpoints) {})
.catch(function (err) {});
```
###### Available Parameters
- tech (string) - Technology of the endpoints (sip,iax2,...)
##### sendMessage
Send a message to some technology URI or endpoint.
Callbacks:
```javascript
ari.endpoints.sendMessage(
{from: val, to: val},
function (err) {}
);
```
Promises:
```javascript
ari.endpoints.sendMessage({
from: val,
to: val
})
.then(function () {})
.catch(function (err) {});
```
###### Available Parameters
- body (string) - The body of the message
- from (string) - The endpoint resource or technology specific identity to send this message from. Valid resources are sip, pjsip, and xmpp.
- to (string) - The endpoint resource or technology specific URI to send the message to. Valid resources are sip, pjsip, and xmpp.
- variables (containers) - undefined
##### sendMessageToEndpoint
Send a message to some endpoint in a technology.
Callbacks:
```javascript
ari.endpoints.sendMessageToEndpoint(
{from: val},
function (err) {}
);
```
Promises:
```javascript
ari.endpoints.sendMessageToEndpoint({
from: val
})
.then(function () {})
.catch(function (err) {});
```
###### Available Parameters
- body (string) - The body of the message
- from (string) - The endpoint resource or technology specific identity to send this message from. Valid resources are sip, pjsip, and xmpp.
- resource (string) - ID of the endpoint
- tech (string) - Technology of the endpoint
- variables (containers) - undefined
#### mailboxes
##### delete
Destroy a mailbox.
Callbacks:
```javascript
ari.mailboxes.delete(
{mailboxName: val},
function (err) {}
);
```
Promises:
```javascript
ari.mailboxes.delete({
mailboxName: val
})
.then(function () {})
.catch(function (err) {});
```
###### Available Parameters
- mailboxName (string) - Name of the mailbox
##### get
Retrieve the current state of a mailbox.
Callbacks:
```javascript
ari.mailboxes.get(
{mailboxName: val},
function (err, mailbox) {}
);
```
Promises:
```javascript
ari.mailboxes.get({
mailboxName: val
})
.then(function (mailbox) {})
.catch(function (err) {});
```
###### Available Parameters
- mailboxName (string) - Name of the mailbox
##### list
List all mailboxes.
Callbacks:
```javascript
ari.mailboxes.list(
function (err, mailboxs) {}
);
```
Promises:
```javascript
ari.mailboxes.list()
.then(function (mailboxs) {})
.catch(function (err) {});
```
##### update
Change the state of a mailbox. (Note - implicitly creates the mailbox).
Callbacks:
```javascript
ari.mailboxes.update(
{mailboxName: val, newMessages: val, oldMessages: val},
function (err) {}
);
```
Promises:
```javascript
ari.mailboxes.update({
mailboxName: val,
newMessages: val,
oldMessages: val
})
.then(function () {})
.catch(function (err) {});
```
###### Available Parameters
- mailboxName (string) - Name of the mailbox
- newMessages (int) - Count of new messages in the mailbox
- oldMessages (int) - Count of old messages in the mailbox
#### playbacks
##### control
Control a playback.
Callbacks:
```javascript
ari.playbacks.control(
{operation: val, playbackId: val},
function (err) {}
);
```
Promises:
```javascript
ari.playbacks.control({
operation: val,
playbackId: val
})
.then(function () {})
.catch(function (err) {});
```
###### Available Parameters
- operation (string) - Operation to perform on the playback.
- playbackId (string) - Playback's id
##### get
Get a playback's details.
Callbacks:
```javascript
ari.playbacks.get(
{playbackId: val},
function (err, playback) {}
);
```
Promises:
```javascript
ari.playbacks.get({
playbackId: val
})
.then(function (playback) {})
.catch(function (err) {});
```
###### Available Parameters
- playbackId (string) - Playback's id
##### stop
Stop a playback.
Callbacks:
```javascript
ari.playbacks.stop(
{playbackId: val},
function (err) {}
);
```
Promises:
```javascript
ari.playbacks.stop({
playbackId: val
})
.then(function () {})
.catch(function (err) {});
```
###### Available Parameters
- playbackId (string) - Playback's id
#### recordings
##### cancel
Stop a live recording and discard it.
Callbacks:
```javascript
ari.recordings.cancel(
{recordingName: val},
function (err) {}
);
```
Promises:
```javascript
ari.recordings.cancel({
recordingName: val
})
.then(function () {})
.catch(function (err) {});
```
###### Available Parameters
- recordingName (string) - The name of the recording
##### copyStored
Copy a stored recording.
Callbacks:
```javascript
ari.recordings.copyStored(
{destinationRecordingName: val, recordingName: val},
function (err, storedrecording) {}
);
```
Promises:
```javascript
ari.recordings.copyStored({
destinationRecordingName: val,
recordingName: val
})
.then(function (storedrecording) {})
.catch(function (err) {});
```
###### Available Parameters
- destinationRecordingName (string) - The destination name of the recording
- recordingName (string) - The name of the recording to copy
##### deleteStored
Delete a stored recording.
Callbacks:
```javascript
ari.recordings.deleteStored(
{recordingName: val},
function (err) {}
);
```
Promises:
```javascript
ari.recordings.deleteStored({
recordingName: val
})
.then(function () {})
.catch(function (err) {});
```
###### Available Parameters
- recordingName (string) - The name of the recording
##### getLive
List live recordings.
Callbacks:
```javascript
ari.recordings.getLive(
{recordingName: val},
function (err, liverecording) {}
);
```
Promises:
```javascript
ari.recordings.getLive({
recordingName: val
})
.then(function (liverecording) {})
.catch(function (err) {});
```
###### Available Parameters
- recordingName (string) - The name of the recording
##### getStored
Get a stored recording's details.
Callbacks:
```javascript
ari.recordings.getStored(
{recordingName: val},
function (err, storedrecording) {}
);
```
Promises:
```javascript
ari.recordings.getStored({
recordingName: val
})
.then(function (storedrecording) {})
.catch(function (err) {});
```
###### Available Parameters
- recordingName (string) - The name of the recording
##### getStoredFile
Get the file associated with the stored recording.
Callbacks:
```javascript
ari.recordings.getStoredFile(
{recordingName: val},
function (err, binary) {}
);
```
Promises:
```javascript
ari.recordings.getStoredFile({
recordingName: val
})
.then(function (binary) {})
.catch(function (err) {});
```
###### Available Parameters
- recordingName (string) - The name of the recording
##### listStored
List recordings that are complete.
Callbacks:
```javascript
ari.recordings.listStored(
function (err, storedrecordings) {}
);
```
Promises:
```javascript
ari.recordings.listStored()
.then(function (storedrecordings) {})
.catch(function (err) {});
```
##### mute
Mute a live recording.
Callbacks:
```javascript
ari.recordings.mute(
{recordingName: val},
function (err) {}
);
```
Promises:
```javascript
ari.recordings.mute({
recordingName: val
})
.then(function () {})
.catch(function (err) {});
```
###### Available Parameters
- recordingName (string) - The name of the recording
##### pause
Pause a live recording.
Callbacks:
```javascript
ari.recordings.pause(
{recordingName: val},
function (err) {}
);
```
Promises:
```javascript
ari.recordings.pause({
recordingName: val
})
.then(function () {})
.catch(function (err) {});
```
###### Available Parameters
- recordingName (string) - The name of the recording
##### stop
Stop a live recording and store it.
Callbacks:
```javascript
ari.recordings.stop(
{recordingName: val},
function (err) {}
);
```
Promises:
```javascript
ari.recordings.stop({
recordingName: val
})
.then(function () {})
.catch(function (err) {});
```
###### Available Parameters
- recordingName (string) - The name of the recording
##### unmute
Unmute a live recording.
Callbacks:
```javascript
ari.recordings.unmute(
{recordingName: val},
function (err) {}
);
```
Promises:
```javascript
ari.recordings.unmute({
recordingName: val
})
.then(function () {})
.catch(function (err) {});
```
###### Available Parameters
- recordingName (string) - The name of the recording
##### unpause
Unpause a live recording.
Callbacks:
```javascript
ari.recordings.unpause(
{recordingName: val},
function (err) {}
);
```
Promises:
```javascript
ari.recordings.unpause({
recordingName: val
})
.then(function () {})
.catch(function (err) {});
```
###### Available Parameters
- recordingName (string) - The name of the recording
#### sounds
##### get
Get a sound's details.
Callbacks:
```javascript
ari.sounds.get(
{soundId: val},
function (err, sound) {}
);
```
Promises:
```javascript
ari.sounds.get({
soundId: val
})
.then(function (sound) {})
.catch(function (err) {});
```
###### Available Parameters
- soundId (string) - Sound's id
##### list
List all sounds.
Callbacks:
```javascript
ari.sounds.list(
function (err, sounds) {}
);
```
Promises:
```javascript
ari.sounds.list()
.then(function (sounds) {})
.catch(function (err) {});
```
###### Available Parameters
- format (string) - Lookup sound in a specific format.
- lang (string) - Lookup sound for a specific language.
### Events
Event listeners can be registered on the client as well as on resource instances.
#### Client Events
Client events are received for all events of a given type regardless of which resource the event is for.
```javascript
ari.on('StasisStart', function (event, channelInstance) {
// will be called for all channels that enter the Stasis application
});
```
#### Resource Instance Events
Resource instance events are only received for the given type and resource.
Callbacks:
```javascript
var channel = ari.Channel();
channel.on('StasisStart', function (event, channelInstance) {
// will only be called when the channel above enters the Stasis application
});
channel.originate(
{endpoint: 'PJSIP/endpoint', app: 'applicationName'},
function (err, channelInstance) {}
);
```
Promises:
```javascript
var channel = ari.Channel();
channel.on('StasisStart', function (event, channelInstance) {
// will only be called when the channel above enters the Stasis application
});
channel.originate({endpoint: 'PJSIP/endpoint', app: 'applicationName'})
.then(function (channelInstance) {})
.catch(function (err) {});
```
#### Managing Events
When using events, it is important to note that the callbacks you provide to handle events cannot be garbage collected until they are unregistered as shown below.
At the client level:
```javascript
var handler = function (event, channel) {};
// receive all 'ChannelDtmfReceived' events
ari.on('ChannelDtmfReceived', handler);
// at some point in your application, remove the event listener to ensure the handler function can be garbage collected
ari.removeListener('ChannelDtmfReceived', handler);
// or remove all event listeners for a particular event type
ari.removeAllListeners('ChannelDtmfReceived');
```
At the instance level:
```javascript
var channel = ari.Channel();
var handler = function (event, channel) {};
// receive all 'ChannelDtmfReceived' events for this channel
channel.on('ChannelDtmfReceived', handler);
// at some point in your application, remove the event listener to ensure the handler function can be garbage collected
channel.removeListener('ChannelDtmfReceived', handler);
// or remove all event listeners for a particular event type
channel.removeAllListeners('ChannelDtmfReceived');
```
For events that are only expected to fire once, `once` can be used to register an event listener that will automatically be unregistered once the event fires as shown below:
```javascript
var playback = ari.Playback();
var handler = function (event, playback) {};
// receive 'PlaybackFinished' events for this playback
playback.once('PlaybackFinished', handler);
```
#### Supported Events
The following events are defined:
##### APILoadError
ARI client failed to load.
```javascript
function (err) {}
```
##### ApplicationMoveFailed
Notification that trying to move a channel to another Stasis application failed.
```javascript
function (event, channel) {}
```
###### Available Event Properties
- args (List[string]) - Arguments to the application
- channel (Channel) - undefined
- destination (string) - undefined
###### Resource Specific Emitters
Channel
##### ApplicationReplaced
Notification that another WebSocket has taken over for an application.
An application may only be subscribed to by a single WebSocket at a time. If multiple WebSockets attempt to subscribe to the same application, the newer WebSocket wins, and the older one receives this event.
```javascript
function (event) {}
```
##### BridgeAttendedTransfer
Notification that an attended transfer has occurred.
```javascript
function (event, {destination_link_first_leg: val, destination_link_second_leg: val, destination_threeway_bridge: val, destination_threeway_channel: val, replace_channel: val, transfer_target: val, transferee: val, transferer_first_leg: val, transferer_first_leg_bridge: val, transferer_second_leg: val, transferer_second_leg_bridge: val}) {}
```
###### Available Event Properties
- destination_application (string) - Application that has been transferred into
- destination_bridge (string) - Bridge that survived the merge result
- destination_link_first_leg (Channel) - First leg of a link transfer result
- destination_link_second_leg (Channel) - Second leg of a link transfer result
- destination_threeway_bridge (Bridge) - Bridge that survived the threeway result
- destination_threeway_channel (Channel) - Transferer channel that survived the threeway result
- destination_type (string) - How the transfer was accomplished
- is_external (boolean) - Whether the transfer was externally initiated or not
- replace_channel (Channel) - The channel that is replacing transferer_first_leg in the swap
- result (string) - The result of the transfer attempt
- transfer_target (Channel) - The channel that is being transferred to
- transferee (Channel) - The channel that is being transferred
- transferer_first_leg (Channel) - First leg of the transferer
- transferer_first_leg_bridge (Bridge) - Bridge the transferer first leg is in
- transferer_second_leg (Channel) - Second leg of the transferer
- transferer_second_leg_bridge (Bridge) - Bridge the transferer second leg is in
###### Resource Specific Emitters
Channel
Bridge
##### BridgeBlindTransfer
Notification that a blind transfer has occurred.
```javascript
function (event, {bridge: val, channel: val, replace_channel: val, transferee: val}) {}
```
###### Available Event Properties
- bridge (Bridge) - The bridge being transferred
- channel (Channel) - The channel performing the blind transfer
- context (string) - The context transferred to
- exten (string) - The extension transferred to
- is_external (boolean) - Whether the transfer was externally initiated or not
- replace_channel (Channel) - The channel that is replacing transferer when the transferee(s) can not be transferred directly
- result (string) - The result of the transfer attempt
- transferee (Channel) - The channel that is being transferred
###### Resource Specific Emitters
Bridge
Channel
##### BridgeCreated
Notification that a bridge has been created.
```javascript
function (event, bridge) {}
```
###### Available Event Properties
- bridge (Bridge) - undefined
###### Resource Specific Emitters
Bridge
##### BridgeDestroyed
Notification that a bridge has been destroyed.
```javascript
function (event, bridge) {}
```
###### Available Event Properties
- bridge (Bridge) - undefined
###### Resource Specific Emitters
Bridge
##### BridgeMerged
Notification that one bridge has merged into another.
```javascript
function (event, {bridge: val, bridge_from: val}) {}
```
###### Available Event Properties
- bridge (Bridge) - undefined
- bridge_from (Bridge) - undefined
###### Resource Specific Emitters
Bridge
##### BridgeVideoSourceChanged
Notification that the source of video in a bridge has changed.
```javascript
function (event, bridge) {}
```
###### Available Event Properties
- bridge (Bridge) - undefined
- old_video_source_id (string) - undefined
###### Resource Specific Emitters
Bridge
##### ChannelCallerId
Channel changed Caller ID.
```javascript
function (event, channel) {}
```
###### Available Event Properties
- caller_presentation (int) - The integer representation of the Caller Presentation value.
- caller_presentation_txt (string) - The text representation of the Caller Presentation value.
- channel (Channel) - The channel that changed Caller ID.
###### Resource Specific Emitters
Channel
##### ChannelConnectedLine
Channel changed Connected Line.
```javascript
function (event, channel) {}
```
###### Available Event Properties
- channel (Channel) - The channel whose connected line has changed.
###### Resource Specific Emitters
Channel
##### ChannelCreated
Notification that a channel has been created.
```javascript
function (event, channel) {}
```
###### Available Event Properties
- channel (Channel) - undefined
###### Resource Specific Emitters
Channel
##### ChannelDestroyed
Notification that a channel has been destroyed.
```javascript
function (event, channel) {}
```
###### Available Event Properties
- cause (int) - Integer representation of the cause of the hangup
- cause_txt (string) - Text representation of the cause of the hangup
- channel (Channel) - undefined
###### Resource Specific Emitters
Channel
##### ChannelDialplan
Channel changed location in the dialplan.
```javascript
function (event, channel) {}
```
###### Available Event Properties
- channel (Channel) - The channel that changed dialplan location.
- dialplan_app (string) - The application about to be executed.
- dialplan_app_data (string) - The data to be passed to the application.
###### Resource Specific Emitters
Channel
##### ChannelDtmfReceived
DTMF received on a channel.
This event is sent when the DTMF ends. There is no notification about the start of DTMF
```javascript
function (event, channel) {}
```
###### Available Event Properties
- channel (Channel) - The channel on which DTMF was received
- digit (string) - DTMF digit received (0-9, A-E, # or *)
- duration_ms (int) - Number of milliseconds DTMF was received
###### Resource Specific Emitters
Channel
##### ChannelEnteredBridge
Notification that a channel has entered a bridge.
```javascript
function (event, {bridge: val, channel: val}) {}
```
###### Available Event Properties
- bridge (Bridge) - undefined
- channel (Channel) - undefined
###### Resource Specific Emitters
Bridge
Channel
##### ChannelHangupRequest
A hangup was requested on the channel.
```javascript
function (event, channel) {}
```
###### Available Event Properties
- cause (int) - Integer representation of the cause of the hangup.
- channel (Channel) - The channel on which the hangup was requested.
- soft (boolean) - Whether the hangup request was a soft hangup request.
###### Resource Specific Emitters
Channel
##### ChannelHold
A channel initiated a media hold.
```javascript
function (event, channel) {}
```
###### Available Event Properties
- channel (Channel) - The channel that initiated the hold event.
- musicclass (string) - The music on hold class that the initiator requested.
###### Resource Specific Emitters
Channel
##### ChannelLeftBridge
Notification that a channel has left a bridge.
```javascript
function (event, {bridge: val, channel: val}) {}
```
###### Available Event Properties
- bridge (Bridge) - undefined
- channel (Channel) - undefined
###### Resource Specific Emitters
Bridge
Channel
##### ChannelStateChange
Notification of a channel's state change.
```javascript
function (event, channel) {}
```
###### Available Event Properties
- channel (Channel) - undefined
###### Resource Specific Emitters
Channel
##### ChannelTalkingFinished
Talking is no longer detected on the channel.
```javascript
function (event, channel) {}
```
###### Available Event Properties
- channel (Channel) - The channel on which talking completed.
- duration (int) - The length of time, in milliseconds, that talking was detected on the channel
###### Resource Specific Emitters
Channel
##### ChannelTalkingStarted
Talking was detected on the channel.
```javascript
function (event, channel) {}
```
###### Available Event Properties
- channel (Channel) - The channel on which talking started.
###### Resource Specific Emitters
Channel
##### ChannelUnhold
A channel initiated a media unhold.
```javascript
function (event, channel) {}
```
###### Available Event Properties
- channel (Channel) - The channel that initiated the unhold event.
###### Resource Specific Emitters
Channel
##### ChannelUserevent
User-generated event with additional user-defined fields in the object.
```javascript
function (event, {bridge: val, channel: val, endpoint: val}) {}
```
###### Available Event Properties
- bridge (Bridge) - A bridge that is signaled with the user event.
- channel (Channel) - A channel that is signaled with the user event.
- endpoint (Endpoint) - A endpoint that is signaled with the user event.
- eventname (string) - The name of the user event.
- userevent (object) - Custom Userevent data
###### Resource Specific Emitters
Bridge
Channel
Endpoint
##### ChannelVarset
Channel variable changed.
```javascript
function (event, channel) {}
```
###### Available Event Properties
- channel (Channel) - The channel on which the variable was set.
If missing, the variable is a global variable.
- value (string) - The new value of the variable.
- variable (string) - The variable that changed.
###### Resource Specific Emitters
Channel
##### ContactInfo
Detailed information about a contact on an endpoint.
```javascript
function (event) {}
```
###### Available Event Properties
- aor (string) - The Address of Record this contact belongs to.
- contact_status (string) - The current status of the contact.
- roundtrip_usec (string) - Current round trip time, in microseconds, for the contact.
- uri (string) - The location of the contact.
##### ContactStatusChange
The state of a contact on an endpoint has changed.
```javascript
function (event, endpoint) {}
```
###### Available Event Properties
- contact_info (ContactInfo) - undefined
- endpoint (Endpoint) - undefined
###### Resource Specific Emitters
Endpoint
##### DeviceStateChanged
Notification that a device state has changed.
```javascript
function (event, device_state) {}
```
###### Available Event Properties
- device_state (DeviceState) - Device state object
###### Resource Specific Emitters
DeviceState
##### Dial
Dialing state has changed.
```javascript
function (event, {caller: val, forwarded: val, peer: val}) {}
```
###### Available Event Properties
- caller (Channel) - The calling channel.
- dialstatus (string) - Current status of the dialing attempt to the peer.
- dialstring (string) - The dial string for calling the peer channel.
- forward (string) - Forwarding target requested by the original dialed channel.
- forwarded (Channel) - Channel that the caller has been forwarded to.
- peer (Channel) - The dialed channel.
###### Resource Specific Emitters
Channel
##### EndpointStateChange
Endpoint state changed.
```javascript
function (event, endpoint) {}
```
###### Available Event Properties
- endpoint (Endpoint) - undefined
###### Resource Specific Emitters
Endpoint
##### MissingParams
Error event sent when required params are missing.
```javascript
function (event) {}
```
###### Available Event Properties
- params (List[string]) - A list of the missing parameters
##### Peer
Detailed information about a remote peer that communicates with Asterisk.
```javascript
function (event) {}
```
###### Available Event Properties
- address (string) - The IP address of the peer.
- cause (string) - An optional reason associated with the change in peer_status.
- peer_status (string) - The current state of the peer. Note that the values of the status are dependent on the underlying peer technology.
- port (string) - The port of the peer.
- time (string) - The last known time the peer was contacted.
##### PeerStatusChange
The state of a peer associated with an endpoint has changed.
```javascript
function (event, endpoint) {}
```
###### Available Event Properties
- endpoint (Endpoint) - undefined
- peer (Peer) - undefined
###### Resource Specific Emitters
Endpoint
##### PlaybackContinuing
Event showing the continuation of a media playback operation from one media URI to the next in the list.
```javascript
function (event, playback) {}
```
###### Available Event Properties
- playback (Playback) - Playback control object
###### Resource Specific Emitters
Playback
##### PlaybackFinished
Event showing the completion of a media playback operation.
```javascript
function (event, playback) {}
```
###### Available Event Properties
- playback (Playback) - Playback control object
###### Resource Specific Emitters
Playback
##### PlaybackStarted
Event showing the start of a media playback operation.
```javascript
function (event, playback) {}
```
###### Available Event Properties
- playback (Playback) - Playback control object
###### Resource Specific Emitters
Playback
##### RecordingFailed
Event showing failure of a recording operation.
```javascript
function (event, recording) {}
```
###### Available Event Properties
- recording (LiveRecording) - Recording control object
###### Resource Specific Emitters
LiveRecording
##### RecordingFinished
Event showing the completion of a recording operation.
```javascript
function (event, recording) {}
```
###### Available Event Properties
- recording (LiveRecording) - Recording control object
###### Resource Specific Emitters
LiveRecording
##### RecordingStarted
Event showing the start of a recording operation.
```javascript
function (event, recording) {}
```
###### Available Event Properties
- recording (LiveRecording) - Recording control object
###### Resource Specific Emitters
LiveRecording
##### StasisEnd
Notification that a channel has left a Stasis application.
```javascript
function (event, channel) {}
```
###### Available Event Properties
- channel (Channel) - undefined
###### Resource Specific Emitters
Channel
##### StasisStart
Notification that a channel has entered a Stasis application.
```javascript
function (event, {channel: val, replace_channel: val}) {}
```
###### Available Event Properties
- args (List[string]) - Arguments to the application
- channel (Channel) - undefined
- replace_channel (Channel) - undefined
###### Resource Specific Emitters
Channel
##### TextMessageReceived
A text message was received from an endpoint.
```javascript
function (event, endpoint) {}
```
###### Available Event Properties
- endpoint (Endpoint) - undefined
- message (TextMessage) - undefined
###### Resource Specific Emitters
Endpoint
##### WebSocketReconnecting
WebSocket has disconnected, and the client is attempting to reconnect.
```JavaScript
function (err) {}
```
##### WebSocketConnected
WebSocket has connected. Note that normally this event is emitted prior to resolving the `connect()` promise, so you probably will not get an even on the initial connection.
```JavaScript
function () {}
```
##### WebSocketMaxRetries
Client will no longer attempt to reconnect to the WebSocket for the current application(s).
```JavaScript
function (err) {}
```
# Examples
Callbacks:
```javascript
var client = require('ari-client'),
util = require('util');
client.connect('http://localhost:8088', 'user', 'secret', client_loaded);
function client_loaded (err, ari) {
if (err) {
throw err; // program will crash if it fails to connect
}
ari.once('StasisStart', channel_joined);
function channel_joined (event, incoming) {
incoming.on('ChannelDtmfReceived', dtmf_received);
incoming.answer(function (err) {
play(incoming, 'sound:hello-world');
});
}
function dtmf_received (event, channel) {
var digit = event.digit;
switch (digit) {
case '#':
play(channel, 'sound:vm-goodbye', function (err) {
channel.hangup(function (err) {
process.exit(0);
});
});
break;
case '*':
play(channel, 'sound:tt-monkeys');
break;
default:
play(channel, util.format('sound:digits/%s', digit));
}
}
function play (channel, sound, callback) {
var playback = ari.Playback();
playback.on('PlaybackFinished', function (event, playback) {
if (callback) {
callback(null);
}
});
channel.play({media: sound}, playback, function (err, playback) {});
}
ari.start('hello');
}
```
Promises:
```javascript
var client = require('ari-client'),
Promise = require('bluebird'),
util = require('util');
client.connect('http://localhost:8088', 'user', 'secret')
.then(function (ari) {
ari.once('StasisStart', channelJoined);
function channelJoined (event, incoming) {
incoming.on('ChannelDtmfReceived', dtmfReceived);
incoming.answer()
.then(function () {
return play(incoming, 'sound:hello-world');
})
.catch(function (err) {});
}
function dtmfReceived (event, channel) {
var digit = event.digit;
switch (digit) {
case '#':
play(channel, 'sound:vm-goodbye')
.then(function () {
return channel.hangup();
})
.finally(function () {
process.exit(0);
});
break;
case '*':
play(channel, 'sound:tt-monkeys');
break;
default:
play(channel, util.format('sound:digits/%s', digit));
}
}
function play (channel, sound) {
var playback = ari.Playback();
return new Promise(function (resolve, reject) {
playback.on('PlaybackFinished', function (event, playback) {
resolve(playback);
});
channel.play({media: sound}, playback)
.catch(function (err) {
reject(err);
});
});
}
ari.start('hello');
})
.done(); // program will crash if it fails to connect
```
# Testing
To run the mocha tests for ari-client, run the following:
```bash
$ npm test
```
The tests run against a mocked ARI REST endpoint and websocket server.
# Development
After cloning the git repository, run the following to install all dev dependencies:
```bash
$ npm install
$ npm link
```
Then run the following to run jshint and mocha tests:
```bash
$ npm test
```
jshint will enforce a minimal style guide. It is also a good idea to create unit tests when adding new features to ari-client.
To generate a test coverage report run the following:
```bash
$ npm run check-coverage
```
This will also ensure a coverage threshold is met by the tests.
Unit test fixtures for ARI resources can be generated from a local asterisk instance by running the following:
```bash
$ grunt genfixtures
```
Once you have done this and loaded a mocked ARI server, individual calls can be mocked using the hock library. Websocket events can be mocked by creating a websocket server and calling its send method. The helpers module exposes methods for creating a mocked ARI server and a mocked websocket server for use in writing unit tests.
Developer documentation can ge generated by running the following:
```bash
$ grunt jsdoc
```
# License
Apache, Version 2.0. Copyright (c) 2014, Digium, Inc. All rights reserved.
[build]: https://travis-ci.org/asterisk/node-ari-client
[build_image]: https://travis-ci.org/asterisk/node-ari-client.svg?branch=master