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

$ 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:

var client = require('ari-client');
client.connect(url, username, password, function (err, ari) {})

Promises:

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:

ari.bridges.list(function (err, bridges) {});
ari.bridges.get({bridgeId: 'uniqueid'}, function (err, bridge) {});

Promises:

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.

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:

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:

var bridge = ari.Bridge();
bridge.create(function (err, bridge) {});

Promises:

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:

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:

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:

var playback = ari.Playback();
channel.play({media: 'sound:hello-world'}, playback, function (err, playback) {});

Promises:

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:

var playback = ari.Playback();
ari.channels.play({
  media: 'sound:hello-world',
  channelId: channel.id,
  playbackId: playback.id
}, function (err, playback) {});

Promises:

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:

ari.applications.filter(
  {applicationName: val},
  function (err, application) {}
);

Promises:

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:

ari.applications.get(
  {applicationName: val},
  function (err, application) {}
);

Promises:

ari.applications.get({
    applicationName: val
})
  .then(function (application) {})
  .catch(function (err) {});

Available Parameters

applicationName (string) - Application's name

list

List all applications.

Callbacks:

ari.applications.list(
  function (err, applications) {}
);

Promises:

ari.applications.list()
  .then(function (applications) {})
  .catch(function (err) {});

Subscribe an application to a event source.

Callbacks:

ari.applications.subscribe(
  {applicationName: val, eventSource: val},
  function (err, application) {}
);

Promises:

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:

ari.applications.unsubscribe(
  {applicationName: val, eventSource: val},
  function (err, application) {}
);

Promises:

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:

ari.asterisk.addLog(
  {configuration: val, logChannelName: val},
  function (err) {}
);

Promises:

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:

ari.asterisk.deleteLog(
  {logChannelName: val},
  function (err) {}
);

Promises:

ari.asterisk.deleteLog({
    logChannelName: val
})
  .then(function () {})
  .catch(function (err) {});

Available Parameters

logChannelName (string) - Log channels name

deleteObject

Delete a dynamic configuration object.

Callbacks:

ari.asterisk.deleteObject(
  {configClass: val, id: val, objectType: val},
  function (err) {}
);

Promises:

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:

ari.asterisk.getGlobalVar(
  {variable: val},
  function (err, variable) {}
);

Promises:

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:

ari.asterisk.getInfo(
  function (err, asteriskinfo) {}
);

Promises:

ari.asterisk.getInfo()
  .then(function (asteriskinfo) {})
  .catch(function (err) {});

Available Parameters

only (string) - Filter information returned

getModule

Get Asterisk module information.

Callbacks:

ari.asterisk.getModule(
  {moduleName: val},
  function (err, module) {}
);

Promises:

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:

ari.asterisk.getObject(
  {configClass: val, id: val, objectType: val},
  function (err, configtuples) {}
);

Promises:

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:

ari.asterisk.listLogChannels(
  function (err, logchannels) {}
);

Promises:

ari.asterisk.listLogChannels()
  .then(function (logchannels) {})
  .catch(function (err) {});

listModules

List Asterisk modules.

Callbacks:

ari.asterisk.listModules(
  function (err, modules) {}
);

Promises:

ari.asterisk.listModules()
  .then(function (modules) {})
  .catch(function (err) {});

loadModule

Load an Asterisk module.

Callbacks:

ari.asterisk.loadModule(
  {moduleName: val},
  function (err) {}
);

Promises:

ari.asterisk.loadModule({
    moduleName: val
})
  .then(function () {})
  .catch(function (err) {});

Available Parameters

moduleName (string) - Module's name

ping

Response pong message.

Callbacks:

ari.asterisk.ping(
  function (err, asteriskping) {}
);

Promises:

ari.asterisk.ping()
  .then(function (asteriskping) {})
  .catch(function (err) {});

reloadModule

Reload an Asterisk module.

Callbacks:

ari.asterisk.reloadModule(
  {moduleName: val},
  function (err) {}
);

Promises:

ari.asterisk.reloadModule({
    moduleName: val
})
  .then(function () {})
  .catch(function (err) {});

Available Parameters

moduleName (string) - Module's name

rotateLog

Rotates a log channel.

Callbacks:

ari.asterisk.rotateLog(
  {logChannelName: val},
  function (err) {}
);

Promises:

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:

ari.asterisk.setGlobalVar(
  {variable: val},
  function (err) {}
);

Promises:

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:

ari.asterisk.unloadModule(
  {moduleName: val},
  function (err) {}
);

Promises:

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:

ari.asterisk.updateObject(
  {configClass: val, id: val, objectType: val},
  function (err, configtuples) {}
);

Promises:

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:

ari.bridges.addChannel(
  {bridgeId: val, channel: val},
  function (err) {}
);

Promises:

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:

ari.bridges.clearVideoSource(
  {bridgeId: val},
  function (err) {}
);

Promises:

ari.bridges.clearVideoSource({
    bridgeId: val
})
  .then(function () {})
  .catch(function (err) {});

Available Parameters

bridgeId (string) - Bridge's id

create

Create a new bridge.

Callbacks:

ari.bridges.create(
  function (err, bridge) {}
);

Promises:

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:

ari.bridges.createWithId(
  {bridgeId: val},
  function (err, bridge) {}
);

Promises:

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:

ari.bridges.destroy(
  {bridgeId: val},
  function (err) {}
);

Promises:

ari.bridges.destroy({
    bridgeId: val
})
  .then(function () {})
  .catch(function (err) {});

Available Parameters

bridgeId (string) - Bridge's id

get

Get bridge details.

Callbacks:

ari.bridges.get(
  {bridgeId: val},
  function (err, bridge) {}
);

Promises:

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:

ari.bridges.list(
  function (err, bridges) {}
);

Promises:

ari.bridges.list()
  .then(function (bridges) {})
  .catch(function (err) {});

play

Start playback of media on a bridge.

Callbacks:

ari.bridges.play(
  {bridgeId: val, media: val},
  function (err, playback) {}
);

Promises:

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:

ari.bridges.playWithId(
  {bridgeId: val, media: val, playbackId: val},
  function (err, playback) {}
);

Promises:

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:

ari.bridges.record(
  {bridgeId: val, format: val, name: val},
  function (err, liverecording) {}
);

Promises:

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:

ari.bridges.removeChannel(
  {bridgeId: val, channel: val},
  function (err) {}
);

Promises:

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:

ari.bridges.setVideoSource(
  {bridgeId: val, channelId: val},
  function (err) {}
);

Promises:

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:

ari.bridges.startMoh(
  {bridgeId: val},
  function (err) {}
);

Promises:

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:

ari.bridges.stopMoh(
  {bridgeId: val},
  function (err) {}
);

Promises:

ari.bridges.stopMoh({
    bridgeId: val
})
  .then(function () {})
  .catch(function (err) {});

Available Parameters

bridgeId (string) - Bridge's id

channels

answer

Answer a channel.

Callbacks:

ari.channels.answer(
  {channelId: val},
  function (err) {}
);

Promises:

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:

ari.channels.continueInDialplan(
  {channelId: val},
  function (err) {}
);

Promises:

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:

ari.channels.create(
  {app: val, endpoint: val},
  function (err, channel) {}
);

Promises:

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:

ari.channels.dial(
  {channelId: val},
  function (err) {}
);

Promises:

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:

ari.channels.externalMedia(
  {app: val, external_host: val, format: val},
  function (err, channel) {}
);

Promises:

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:

ari.channels.get(
  {channelId: val},
  function (err, channel) {}
);

Promises:

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:

ari.channels.getChannelVar(
  {channelId: val, variable: val},
  function (err, variable) {}
);

Promises:

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:

ari.channels.hangup(
  {channelId: val},
  function (err) {}
);

Promises:

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:

ari.channels.hold(
  {channelId: val},
  function (err) {}
);

Promises:

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:

ari.channels.list(
  function (err, channels) {}
);

Promises:

ari.channels.list()
  .then(function (channels) {})
  .catch(function (err) {});

move

Move the channel from one Stasis application to another.

Callbacks:

ari.channels.move(
  {app: val, channelId: val},
  function (err) {}
);

Promises:

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:

ari.channels.mute(
  {channelId: val},
  function (err) {}
);

Promises:

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:

ari.channels.originate(
  {endpoint: val},
  function (err, channel) {}
);

Promises:

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:

ari.channels.originateWithId(
  {channelId: val, endpoint: val},
  function (err, channel) {}
);

Promises:

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:

ari.channels.play(
  {channelId: val, media: val},
  function (err, playback) {}
);

Promises:

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:

ari.channels.playWithId(
  {channelId: val, media: val, playbackId: val},
  function (err, playback) {}
);

Promises:

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:

ari.channels.record(
  {channelId: val, format: val, name: val},
  function (err, liverecording) {}
);

Promises:

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:

ari.channels.redirect(
  {channelId: val, endpoint: val},
  function (err) {}
);

Promises:

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:

ari.channels.ring(
  {channelId: val},
  function (err) {}
);

Promises:

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:

ari.channels.ringStop(
  {channelId: val},
  function (err) {}
);

Promises:

ari.channels.ringStop({
    channelId: val
})
  .then(function () {})
  .catch(function (err) {});

Available Parameters

channelId (string) - Channel's id

rtpstatistics

RTP stats on a channel.

Callbacks:

ari.channels.rtpstatistics(
  {channelId: val},
  function (err, rtpstat) {}
);

Promises:

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:

ari.channels.sendDTMF(
  {channelId: val},
  function (err) {}
);

Promises:

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:

ari.channels.setChannelVar(
  {channelId: val, variable: val},
  function (err) {}
);

Promises:

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:

ari.channels.snoopChannel(
  {app: val, channelId: val},
  function (err, channel) {}
);

Promises:

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:

ari.channels.snoopChannelWithId(
  {app: val, channelId: val, snoopId: val},
  function (err, channel) {}
);

Promises:

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:

ari.channels.startMoh(
  {channelId: val},
  function (err) {}
);

Promises:

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:

ari.channels.startSilence(
  {channelId: val},
  function (err) {}
);

Promises:

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:

ari.channels.stopMoh(
  {channelId: val},
  function (err) {}
);

Promises:

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:

ari.channels.stopSilence(
  {channelId: val},
  function (err) {}
);

Promises:

ari.channels.stopSilence({
    channelId: val
})
  .then(function () {})
  .catch(function (err) {});

Available Parameters

channelId (string) - Channel's id

unhold

Remove a channel from hold.

Callbacks:

ari.channels.unhold(
  {channelId: val},
  function (err) {}
);

Promises:

ari.channels.unhold({
    channelId: val
})
  .then(function () {})
  .catch(function (err) {});

Available Parameters

channelId (string) - Channel's id

unmute

Unmute a channel.

Callbacks:

ari.channels.unmute(
  {channelId: val},
  function (err) {}
);

Promises:

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:

ari.deviceStates.delete(
  {deviceName: val},
  function (err) {}
);

Promises:

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:

ari.deviceStates.get(
  {deviceName: val},
  function (err, devicestate) {}
);

Promises:

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:

ari.deviceStates.list(
  function (err, devicestates) {}
);

Promises:

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:

ari.deviceStates.update(
  {deviceName: val, deviceState: val},
  function (err) {}
);

Promises:

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:

ari.endpoints.get(
  function (err, endpoint) {}
);

Promises:

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:

ari.endpoints.list(
  function (err, endpoints) {}
);

Promises:

ari.endpoints.list()
  .then(function (endpoints) {})
  .catch(function (err) {});

listByTech

List available endoints for a given endpoint technology.

Callbacks:

ari.endpoints.listByTech(
  function (err, endpoints) {}
);

Promises:

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:

ari.endpoints.sendMessage(
  {from: val, to: val},
  function (err) {}
);

Promises:

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:

ari.endpoints.sendMessageToEndpoint(
  {from: val},
  function (err) {}
);

Promises:

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:

ari.mailboxes.delete(
  {mailboxName: val},
  function (err) {}
);

Promises:

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:

ari.mailboxes.get(
  {mailboxName: val},
  function (err, mailbox) {}
);

Promises:

ari.mailboxes.get({
    mailboxName: val
})
  .then(function (mailbox) {})
  .catch(function (err) {});

Available Parameters

mailboxName (string) - Name of the mailbox

list

List all mailboxes.

Callbacks:

ari.mailboxes.list(
  function (err, mailboxs) {}
);

Promises:

ari.mailboxes.list()
  .then(function (mailboxs) {})
  .catch(function (err) {});

update

Change the state of a mailbox. (Note - implicitly creates the mailbox).

Callbacks:

ari.mailboxes.update(
  {mailboxName: val, newMessages: val, oldMessages: val},
  function (err) {}
);

Promises:

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:

ari.playbacks.control(
  {operation: val, playbackId: val},
  function (err) {}
);

Promises:

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:

ari.playbacks.get(
  {playbackId: val},
  function (err, playback) {}
);

Promises:

ari.playbacks.get({
    playbackId: val
})
  .then(function (playback) {})
  .catch(function (err) {});

Available Parameters

playbackId (string) - Playback's id

stop

Stop a playback.

Callbacks:

ari.playbacks.stop(
  {playbackId: val},
  function (err) {}
);

Promises:

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:

ari.recordings.cancel(
  {recordingName: val},
  function (err) {}
);

Promises:

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:

ari.recordings.copyStored(
  {destinationRecordingName: val, recordingName: val},
  function (err, storedrecording) {}
);

Promises:

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:

ari.recordings.deleteStored(
  {recordingName: val},
  function (err) {}
);

Promises:

ari.recordings.deleteStored({
    recordingName: val
})
  .then(function () {})
  .catch(function (err) {});

Available Parameters

recordingName (string) - The name of the recording

getLive

List live recordings.

Callbacks:

ari.recordings.getLive(
  {recordingName: val},
  function (err, liverecording) {}
);

Promises:

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:

ari.recordings.getStored(
  {recordingName: val},
  function (err, storedrecording) {}
);

Promises:

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:

ari.recordings.getStoredFile(
  {recordingName: val},
  function (err, binary) {}
);

Promises:

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:

ari.recordings.listStored(
  function (err, storedrecordings) {}
);

Promises:

ari.recordings.listStored()
  .then(function (storedrecordings) {})
  .catch(function (err) {});

mute

Mute a live recording.

Callbacks:

ari.recordings.mute(
  {recordingName: val},
  function (err) {}
);

Promises:

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:

ari.recordings.pause(
  {recordingName: val},
  function (err) {}
);

Promises:

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:

ari.recordings.stop(
  {recordingName: val},
  function (err) {}
);

Promises:

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:

ari.recordings.unmute(
  {recordingName: val},
  function (err) {}
);

Promises:

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:

ari.recordings.unpause(
  {recordingName: val},
  function (err) {}
);

Promises:

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:

ari.sounds.get(
  {soundId: val},
  function (err, sound) {}
);

Promises:

ari.sounds.get({
    soundId: val
})
  .then(function (sound) {})
  .catch(function (err) {});

Available Parameters

soundId (string) - Sound's id

list

List all sounds.

Callbacks:

ari.sounds.list(
  function (err, sounds) {}
);

Promises:

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.

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:

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:

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:

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:

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:

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.

function (err) {}

ApplicationMoveFailed

Notification that trying to move a channel to another Stasis application failed.

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.

function (event) {}

BridgeAttendedTransfer

Notification that an attended transfer has occurred.

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.

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.

function (event, bridge) {}

Available Event Properties

bridge (Bridge) - undefined

Resource Specific Emitters

Bridge

BridgeDestroyed

Notification that a bridge has been destroyed.

function (event, bridge) {}

Available Event Properties

bridge (Bridge) - undefined

Resource Specific Emitters

Bridge

BridgeMerged

Notification that one bridge has merged into another.

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.

function (event, bridge) {}

Available Event Properties

bridge (Bridge) - undefined
old_video_source_id (string) - undefined

Resource Specific Emitters

Bridge

ChannelCallerId

Channel changed Caller ID.

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.

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.

function (event, channel) {}

Available Event Properties

channel (Channel) - undefined

Resource Specific Emitters

Channel

ChannelDestroyed

Notification that a channel has been destroyed.

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.

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

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.

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.

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.

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.

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.

function (event, channel) {}

Available Event Properties

channel (Channel) - undefined

Resource Specific Emitters

Channel

ChannelTalkingFinished

Talking is no longer detected on the channel.

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.

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.

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.

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.

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.

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.

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.

function (event, device_state) {}

Available Event Properties

device_state (DeviceState) - Device state object

Resource Specific Emitters

DeviceState

Dial

Dialing state has changed.

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.

function (event, endpoint) {}

Available Event Properties

endpoint (Endpoint) - undefined

Resource Specific Emitters

Endpoint

MissingParams

Error event sent when required params are missing.

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.

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.

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.

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.

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.

function (event, playback) {}

Available Event Properties

playback (Playback) - Playback control object

Resource Specific Emitters

Playback

RecordingFailed

Event showing failure of a recording operation.

function (event, recording) {}

Available Event Properties

recording (LiveRecording) - Recording control object

Resource Specific Emitters

LiveRecording

RecordingFinished

Event showing the completion of a recording operation.

function (event, recording) {}

Available Event Properties

recording (LiveRecording) - Recording control object

Resource Specific Emitters

LiveRecording

RecordingStarted

Event showing the start of a recording operation.

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.

function (event, channel) {}

Available Event Properties

channel (Channel) - undefined

Resource Specific Emitters

Channel

StasisStart

Notification that a channel has entered a Stasis application.

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.

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.

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.

function () {}

WebSocketMaxRetries

Client will no longer attempt to reconnect to the WebSocket for the current application(s).

function (err) {}

Examples

Callbacks:

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:

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:

$ 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:

$ npm install
$ npm link

Then run the following to run jshint and mocha tests:

$ 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:

$ 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:

$ 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:

$ grunt jsdoc