ari-client

JavaScript client for Asterisk REST Interface.

About

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

$ npm install ari-client 

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.

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

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.

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

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.

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

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.

var channel = ari.Channel();
channel.on('StasisStart', function (eventchannel) {});
channel.on('ChannelDtmfReceived', function (eventchannel) {});
channel.originate(
    {endpoint: 'SIP/1000', app: 'application', appArgs: 'dialed'},
    function(errchannel) {}
);

Some create operations require an instance be passed in for this to work.

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

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.

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

The following operations are defined:

Get details of an application.

ari.applications.get(
  {applicationName: val},
  function (errapplication) {}
);
  • applicationName (string) - Application's name

List all applications.

ari.applications.list(
  function (errapplications) {}
);

Subscribe an application to a event source.

ari.applications.subscribe(
  {applicationName: val, eventSource: val},
  function (errapplication) {}
);
  • applicationName (string) - Application's name
  • eventSource (string) - URI for event source (channel:{channelId}, bridge:{bridgeId}, endpoint:{tech}[/{resource}], deviceState:{deviceName}

Unsubscribe an application from an event source.

ari.applications.unsubscribe(
  {applicationName: val, eventSource: val},
  function (errapplication) {}
);
  • applicationName (string) - Application's name
  • eventSource (string) - URI for event source (channel:{channelId}, bridge:{bridgeId}, endpoint:{tech}[/{resource}], deviceState:{deviceName}

Get the value of a global variable.

ari.asterisk.getGlobalVar(
  {variable: val},
  function (errvariable) {}
);
  • variable (string) - The variable to get

Gets Asterisk system information.

ari.asterisk.getInfo(
  function (errasteriskinfo) {}
);
  • only (string) - Filter information returned

Set the value of a global variable.

ari.asterisk.setGlobalVar(
  {variable: val},
  function (err) {}
);
  • value (string) - The value to set the variable to
  • variable (string) - The variable to set

Add a channel to a bridge.

ari.bridges.addChannel(
  {bridgeId: val, channel: val},
  function (err) {}
);
  • bridgeId (string) - Bridge's id
  • channel (string) - Ids of channels to add to bridge
  • role (string) - Channel's role in the bridge

Create a new bridge.

ari.bridges.create(
  function (errbridge) {}
);
  • 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).

Create a new bridge or updates an existing one.

ari.bridges.create_or_update_with_id(
  {bridgeId: val},
  function (errbridge) {}
);
  • 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) to set.

Shut down a bridge.

ari.bridges.destroy(
  {bridgeId: val},
  function (err) {}
);
  • bridgeId (string) - Bridge's id

Get bridge details.

ari.bridges.get(
  {bridgeId: val},
  function (errbridge) {}
);
  • bridgeId (string) - Bridge's id

List all active bridges in Asterisk.

ari.bridges.list(
  function (errbridges) {}
);

Start playback of media on a bridge.

ari.bridges.play(
  {bridgeId: val, media: val},
  function (errplayback) {}
);
  • bridgeId (string) - Bridge's id
  • lang (string) - For sounds, selects language for sound.
  • media (string) - Media's URI to play.
  • offsetms (int) - Number of media to skip before playing.
  • playbackId (string) - Playback Id.
  • skipms (int) - Number of milliseconds to skip for forward/reverse operations.

Start playback of media on a bridge.

ari.bridges.playWithId(
  {bridgeId: val, media: val, playbackId: val},
  function (errplayback) {}
);
  • bridgeId (string) - Bridge's id
  • lang (string) - For sounds, selects language for sound.
  • media (string) - Media's URI to play.
  • offsetms (int) - Number of media to skip before playing.
  • playbackId (string) - Playback ID.
  • skipms (int) - Number of milliseconds to skip for forward/reverse operations.

Start a recording.

ari.bridges.record(
  {bridgeId: val, format: val, name: val},
  function (errliverecording) {}
);
  • 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.

Remove a channel from a bridge.

ari.bridges.removeChannel(
  {bridgeId: val, channel: val},
  function (err) {}
);
  • bridgeId (string) - Bridge's id
  • channel (string) - Ids of channels to remove from bridge

Play music on hold to a bridge or change the MOH class that is playing.

ari.bridges.startMoh(
  {bridgeId: val},
  function (err) {}
);
  • bridgeId (string) - Bridge's id
  • mohClass (string) - Channel's id

Stop playing music on hold to a bridge.

ari.bridges.stopMoh(
  {bridgeId: val},
  function (err) {}
);
  • bridgeId (string) - Bridge's id

Answer a channel.

ari.channels.answer(
  {channelId: val},
  function (err) {}
);
  • channelId (string) - Channel's id

Exit application; continue execution in the dialplan.

ari.channels.continueInDialplan(
  {channelId: val},
  function (err) {}
);
  • channelId (string) - Channel's id
  • context (string) - The context to continue to.
  • extension (string) - The extension to continue to.
  • priority (int) - The priority to continue to.

Channel details.

ari.channels.get(
  {channelId: val},
  function (errchannel) {}
);
  • channelId (string) - Channel's id

Get the value of a channel variable or function.

ari.channels.getChannelVar(
  {channelId: val, variable: val},
  function (errvariable) {}
);
  • channelId (string) - Channel's id
  • variable (string) - The channel variable or function to get

Delete (i.e. hangup) a channel.

ari.channels.hangup(
  {channelId: val},
  function (err) {}
);
  • channelId (string) - Channel's id
  • reason (string) - Reason for hanging up the channel

Hold a channel.

ari.channels.hold(
  {channelId: val},
  function (err) {}
);
  • channelId (string) - Channel's id

List all active channels in Asterisk.

ari.channels.list(
  function (errchannels) {}
);

Mute a channel.

ari.channels.mute(
  {channelId: val},
  function (err) {}
);
  • channelId (string) - Channel's id
  • direction (string) - Direction in which to mute audio

Create a new channel (originate).

ari.channels.originate(
  {endpoint: val},
  function (errchannel) {}
);
  • app (string) - The application that is subscribed to the originated channel, and passed to the Stasis application.
  • appArgs (string) - The application arguments to pass to the Stasis application.
  • 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'
  • endpoint (string) - Endpoint to call.
  • extension (string) - The extension to dial after the endpoint answers
  • 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
  • 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" } }

Create a new channel (originate with id).

ari.channels.originateWithId(
  {channelId: val, endpoint: val},
  function (errchannel) {}
);
  • app (string) - The application that is subscribed to the originated channel, and passed to the Stasis application.
  • appArgs (string) - The application arguments to pass to the Stasis application.
  • 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'
  • endpoint (string) - Endpoint to call.
  • extension (string) - The extension to dial after the endpoint answers
  • 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
  • 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" } }

Start playback of media.

ari.channels.play(
  {channelId: val, media: val},
  function (errplayback) {}
);
  • channelId (string) - Channel's id
  • lang (string) - For sounds, selects language for sound.
  • media (string) - Media's URI to play.
  • offsetms (int) - Number of media to skip before playing.
  • playbackId (string) - Playback ID.
  • skipms (int) - Number of milliseconds to skip for forward/reverse operations.

Start playback of media and specify the playbackId.

ari.channels.playWithId(
  {channelId: val, media: val, playbackId: val},
  function (errplayback) {}
);
  • channelId (string) - Channel's id
  • lang (string) - For sounds, selects language for sound.
  • media (string) - Media's URI to play.
  • offsetms (int) - Number of media to skip before playing.
  • playbackId (string) - Playback ID.
  • skipms (int) - Number of milliseconds to skip for forward/reverse operations.

Start a recording.

ari.channels.record(
  {channelId: val, format: val, name: val},
  function (errliverecording) {}
);
  • 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

Indicate ringing to a channel.

ari.channels.ring(
  {channelId: val},
  function (err) {}
);
  • channelId (string) - Channel's id

Stop ringing indication on a channel if locally generated.

ari.channels.ringStop(
  {channelId: val},
  function (err) {}
);
  • channelId (string) - Channel's id

Send provided DTMF to a given channel.

ari.channels.sendDTMF(
  {channelId: val},
  function (err) {}
);
  • 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).

Set the value of a channel variable or function.

ari.channels.setChannelVar(
  {channelId: val, variable: val},
  function (err) {}
);
  • channelId (string) - Channel's id
  • value (string) - The value to set the variable to
  • variable (string) - The channel variable or function to set

Start snooping.

ari.channels.snoopChannel(
  {app: val, channelId: val},
  function (errchannel) {}
);
  • 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

Start snooping.

ari.channels.snoopChannelWithId(
  {app: val, channelId: val, snoopId: val},
  function (errchannel) {}
);
  • 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

Play music on hold to a channel.

ari.channels.startMoh(
  {channelId: val},
  function (err) {}
);
  • channelId (string) - Channel's id
  • mohClass (string) - Music on hold class to use

Play silence to a channel.

ari.channels.startSilence(
  {channelId: val},
  function (err) {}
);
  • channelId (string) - Channel's id

Stop playing music on hold to a channel.

ari.channels.stopMoh(
  {channelId: val},
  function (err) {}
);
  • channelId (string) - Channel's id

Stop playing silence to a channel.

ari.channels.stopSilence(
  {channelId: val},
  function (err) {}
);
  • channelId (string) - Channel's id

Remove a channel from hold.

ari.channels.unhold(
  {channelId: val},
  function (err) {}
);
  • channelId (string) - Channel's id

Unmute a channel.

ari.channels.unmute(
  {channelId: val},
  function (err) {}
);
  • channelId (string) - Channel's id
  • direction (string) - Direction in which to unmute audio

Destroy a device-state controlled by ARI.

ari.deviceStates.delete(
  {deviceName: val},
  function (err) {}
);
  • deviceName (string) - Name of the device

Retrieve the current state of a device.

ari.deviceStates.get(
  {deviceName: val},
  function (errdevicestate) {}
);
  • deviceName (string) - Name of the device

List all ARI controlled device states.

ari.deviceStates.list(
  function (errdevicestates) {}
);

Change the state of a device controlled by ARI. (Note - implicitly creates the device state).

ari.deviceStates.update(
  {deviceName: val, deviceState: val},
  function (err) {}
);
  • deviceName (string) - Name of the device
  • deviceState (string) - Device state value

Details for an endpoint.

ari.endpoints.get(
  function (errendpoint) {}
);
  • resource (string) - ID of the endpoint
  • tech (string) - Technology of the endpoint

List all endpoints.

ari.endpoints.list(
  function (errendpoints) {}
);

List available endoints for a given endpoint technology.

ari.endpoints.listByTech(
  function (errendpoints) {}
);
  • tech (string) - Technology of the endpoints (sip,iax2,...)

Send a message to some technology URI or endpoint.

ari.endpoints.sendMessage(
  {from: val, to: val},
  function (err) {}
);
  • 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

Send a message to some endpoint in a technology.

ari.endpoints.sendMessageToEndpoint(
  {from: val},
  function (err) {}
);
  • 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

Destroy a mailbox.

ari.mailboxes.delete(
  {mailboxName: val},
  function (err) {}
);
  • mailboxName (string) - Name of the mailbox

Retrieve the current state of a mailbox.

ari.mailboxes.get(
  {mailboxName: val},
  function (errmailbox) {}
);
  • mailboxName (string) - Name of the mailbox

List all mailboxes.

ari.mailboxes.list(
  function (errmailboxs) {}
);

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

ari.mailboxes.update(
  {mailboxName: val, newMessages: val, oldMessages: val},
  function (err) {}
);
  • mailboxName (string) - Name of the mailbox
  • newMessages (int) - Count of new messages in the mailbox
  • oldMessages (int) - Count of old messages in the mailbox

Control a playback.

ari.playbacks.control(
  {operation: val, playbackId: val},
  function (err) {}
);
  • operation (string) - Operation to perform on the playback.
  • playbackId (string) - Playback's id

Get a playback's details.

ari.playbacks.get(
  {playbackId: val},
  function (errplayback) {}
);
  • playbackId (string) - Playback's id

Stop a playback.

ari.playbacks.stop(
  {playbackId: val},
  function (err) {}
);
  • playbackId (string) - Playback's id

Stop a live recording and discard it.

ari.recordings.cancel(
  {recordingName: val},
  function (err) {}
);
  • recordingName (string) - The name of the recording

Copy a stored recording.

ari.recordings.copyStored(
  {destinationRecordingName: val, recordingName: val},
  function (errstoredrecording) {}
);
  • destinationRecordingName (string) - The destination name of the recording
  • recordingName (string) - The name of the recording to copy

Delete a stored recording.

ari.recordings.deleteStored(
  {recordingName: val},
  function (err) {}
);
  • recordingName (string) - The name of the recording

List live recordings.

ari.recordings.getLive(
  {recordingName: val},
  function (errliverecording) {}
);
  • recordingName (string) - The name of the recording

Get a stored recording's details.

ari.recordings.getStored(
  {recordingName: val},
  function (errstoredrecording) {}
);
  • recordingName (string) - The name of the recording

List recordings that are complete.

ari.recordings.listStored(
  function (errstoredrecordings) {}
);

Mute a live recording.

ari.recordings.mute(
  {recordingName: val},
  function (err) {}
);
  • recordingName (string) - The name of the recording

Pause a live recording.

ari.recordings.pause(
  {recordingName: val},
  function (err) {}
);
  • recordingName (string) - The name of the recording

Stop a live recording and store it.

ari.recordings.stop(
  {recordingName: val},
  function (err) {}
);
  • recordingName (string) - The name of the recording

Unmute a live recording.

ari.recordings.unmute(
  {recordingName: val},
  function (err) {}
);
  • recordingName (string) - The name of the recording

Unpause a live recording.

ari.recordings.unpause(
  {recordingName: val},
  function (err) {}
);
  • recordingName (string) - The name of the recording

Get a sound's details.

ari.sounds.get(
  {soundId: val},
  function (errsound) {}
);
  • soundId (string) - Sound's id

List all sounds.

ari.sounds.list(
  function (errsounds) {}
);
  • format (string) - Lookup sound in a specific format.
  • lang (string) - Lookup sound for a specific language.

Event listeners can be registered on the client as well as on resource instances. Note that resource instance listeners are tied to the instance while client listeners receive all events of a given type regardless of which resource the event is for.

The following events are defined:

ARI client failed to load.

function (err) {}

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) {}

Notification that an attended transfer has occurred.

function (event, {destination_link_first_leg: valdestination_link_second_leg: valdestination_threeway_bridge: valdestination_threeway_channel: valreplace_channel: valtransfer_target: valtransferee: valtransferer_first_leg: valtransferer_first_leg_bridge: valtransferer_second_leg: valtransferer_second_leg_bridge: val}) {}
  • 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

Channel Bridge

Notification that a blind transfer has occurred.

function (event, {bridge: valchannel: valreplace_channel: valtransferee: val}) {}
  • 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

Bridge Channel

Notification that a bridge has been created.

function (eventbridge) {}
  • bridge (Bridge) - undefined

Bridge

Notification that a bridge has been destroyed.

function (eventbridge) {}
  • bridge (Bridge) - undefined

Bridge

Notification that one bridge has merged into another.

function (event, {bridge: valbridge_from: val}) {}
  • bridge (Bridge) - undefined
  • bridge_from (Bridge) - undefined

Bridge

Channel changed Caller ID.

function (eventchannel) {}
  • 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.

Channel

Notification that a channel has been created.

function (eventchannel) {}
  • channel (Channel) - undefined

Channel

Notification that a channel has been destroyed.

function (eventchannel) {}
  • cause (int) - Integer representation of the cause of the hangup
  • cause_txt (string) - Text representation of the cause of the hangup
  • channel (Channel) - undefined

Channel

Channel changed location in the dialplan.

function (eventchannel) {}
  • 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.

Channel

DTMF received on a channel.

This event is sent when the DTMF ends. There is no notification about the start of DTMF

function (eventchannel) {}
  • 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

Channel

Notification that a channel has entered a bridge.

function (event, {bridge: valchannel: val}) {}
  • bridge (Bridge) - undefined
  • channel (Channel) - undefined

Bridge Channel

A hangup was requested on the channel.

function (eventchannel) {}
  • 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.

Channel

Notification that a channel has left a bridge.

function (event, {bridge: valchannel: val}) {}
  • bridge (Bridge) - undefined
  • channel (Channel) - undefined

Bridge Channel

Notification of a channel's state change.

function (eventchannel) {}
  • channel (Channel) - undefined

Channel

Talking is no longer detected on the channel.

function (eventchannel) {}
  • channel (Channel) - The channel on which talking completed.
  • duration (int) - The length of time, in milliseconds, that talking was detected on the channel

Channel

Talking was detected on the channel.

function (eventchannel) {}
  • channel (Channel) - The channel on which talking started.

Channel

User-generated event with additional user-defined fields in the object.

function (event, {bridge: valchannel: valendpoint: val}) {}
  • 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

Bridge Channel Endpoint

Channel variable changed.

function (eventchannel) {}
  • 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.

Channel

Notification that a device state has changed.

function (eventdevice_state) {}
  • device_state (DeviceState) - Device state object

DeviceState

Dialing state has changed.

function (event, {caller: valforwarded: valpeer: val}) {}
  • 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.

Channel

Endpoint state changed.

function (eventendpoint) {}
  • endpoint (Endpoint) - undefined

Endpoint

Error event sent when required params are missing.

function (event) {}
  • params (List[string]) - A list of the missing parameters

Event showing the completion of a media playback operation.

function (eventplayback) {}
  • playback (Playback) - Playback control object

Playback

Event showing the start of a media playback operation.

function (eventplayback) {}
  • playback (Playback) - Playback control object

Playback

Event showing failure of a recording operation.

function (eventrecording) {}
  • recording (LiveRecording) - Recording control object

LiveRecording

Event showing the completion of a recording operation.

function (eventrecording) {}
  • recording (LiveRecording) - Recording control object

LiveRecording

Event showing the start of a recording operation.

function (eventrecording) {}
  • recording (LiveRecording) - Recording control object

LiveRecording

Notification that a channel has left a Stasis application.

function (eventchannel) {}
  • channel (Channel) - undefined

Channel

Notification that a channel has entered a Stasis application.

function (event, {channel: valreplace_channel: val}) {}
  • args (List[string]) - Arguments to the application
  • channel (Channel) - undefined
  • replace_channel (Channel) - undefined

Channel

A text message was received from an endpoint.

function (eventendpoint) {}
  • endpoint (Endpoint) - undefined
  • message (TextMessage) - undefined

Endpoint

Examples

Replace ari.js with your Asterisk instance.

var client = require('ari-client'), 
    util = require('util');
 
client.connect('http://ari.js:8088', 'user', 'secret', client_loaded);
 
function client_loaded (errari) {
 
    ari.once('StasisStart', channel_joined);
 
    function channel_joined (eventincoming) {
        incoming.on('ChannelDtmfReceived', dtmf_received);
 
        incoming.answer(function (err) {
            play(incoming, 'sound:hello-world');
        });
    }
 
    function dtmf_received (eventchannel) {
        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 (channelsoundcallback) {
        var playback = ari.Playback();
        playback.on('PlaybackFinished', function (eventplayback) {
            if (callback) {
                callback(null);
            }
        });
        channel.play({media: sound}, playback, function (errplayback) { });
    }
 
    ari.start('hello');
}

Testing

To run the mocha tests for ari-client, run the following:

grunt mochaTest

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:

grunt

jshint will enforce a minimal style guide. It is also a good idea to create unit tests when adding new features to ari-client.

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

License

Apache, Version 2.0. Copyright (c) 2014, Digium, Inc. All rights reserved.