Asterisk AMI Client for NodeJS (ES2015)

Full functionality client for Asterisk's AMI. Support any data packages (action/event/response/custom responses) from AMI; With this client you can select you'r own case of programming interactions with Asterisk AMI.

If you like events & handlers - you can use it!
If you like promises - you can use it!
If you like co & sync-style of code - you can use it!

Install
Usage
- Example 1
- Example 2
- Example 3
- Example 4
- Example 5
More examples
Docs & internal details
Tests
License

Install

$ npm i asterisk-ami-client

NodeJS versions

support >=4.0.0

Usage

It is only some usage cases.

Example 1:

Listening all events on instance of client;

const AmiClient = require('asterisk-ami-client');
let client = new AmiClient();
 
client.connect('user', 'secret', {host: 'localhost', port: 5038})
 .then(amiConnection => {
 
     client
         .on('connect', () => console.log('connect'))
         .on('event', event => console.log(event))
         .on('data', chunk => console.log(chunk))
         .on('response', response => console.log(response))
         .on('disconnect', () => console.log('disconnect'))
         .on('reconnection', () => console.log('reconnection'))
         .on('internalError', error => console.log(error))
         .action({
             Action: 'Ping'
         });
 
     setTimeout(() => {
         client.disconnect();
     }, 5000);
 
 })
 .catch(error => console.log(error));

Example 2:

Receive Asterisk's AMI responses with promise-chunk.

const AmiClient = require('asterisk-ami-client');
let client = new AmiClient({reconnect: true});
 
client.connect('username', 'secret', {host: '127.0.0.1', port: 5038})
    .then(() => { // any action after connection
        return client.action({Action: 'Ping'}, true);
    })
    .then(response1 => { // response of first action
        console.log(response1);
    })
    .then(() => { // any second action
        return client.action({Action: 'Ping'}, true);
    })
    .then(response2 => { // response of second action
        console.log(response2)
    })
    .catch(error => error)
    .then(error => {
        client.disconnect(); // disconnect
        if(error instanceof Error){ throw error; }
    });

or with co-library for sync-style of code

Example 3:

Receive Asterisk's AMI responses with co.

const AmiClient = require('asterisk-ami-client');
const co = require('co');
 
let client = new AmiClient({reconnect: true});
 
co(function* (){
    yield client.connect('username', 'secret', {host: '127.0.0.1', port: 5038});
 
    let response1 = yield client.action({Action: 'Ping'}, true);
    console.log(response1);
 
    let response2 = yield client.action({Action: 'Ping'}, true);
    console.log(response2);
 
    client.disconnect();
}).catch(error => console.log(error));

Example 4:

Listening event and response events on instance of client.

const AmiClient = require('asterisk-ami-client');
 
let client = new AmiClient({
    reconnect: true,
    keepAlive: true
});
 
client.connect('user', 'secret', {host: 'localhost', port: 5038})
    .then(() => {
        client
            .on('event', event => console.log(event))
            .on('response', response => {
                console.log(response);
                client.disconnect();
            })
            .on('internalError', error => console.log(error));
 
        client.action({Action: 'Ping'});
    })
    .catch(error => console.log(error));

Example 5:

Emit events by names and emit of response by resp_${ActionID} (if ActionID is set in action's data package).

const AmiClient = require('asterisk-ami-client');
 
let client = new AmiClient({
    reconnect: true,
    keepAlive: true,
    emitEventsByTypes: true,
    emitResponsesById: true
});
 
client.connect('user', 'secret', {host: 'localhost', port: 5038})
    .then(() => {
        client
            .on('Dial', event => console.log(event))
            .on('Hangup', event => console.log(event))
            .on('Hold', event => console.log(event))
            .on('Bridge', event => console.log(event))
            .on('resp_123', response => {
                console.log(response);
                client.disconnect();
            })
            .on('internalError', error => console.log(error));
 
        client.action({
            Action: 'Ping',
            ActionID: 123
        });
    })
    .catch(error => console.log(error));

More examples

For more examples, please, see ./examples/*.

Docs & internal details

Events

connect - emits when client was connected;
event - emits when was received a new event of Asterisk;
data - emits when was received a new chunk of data form the Asterisk's socket;
response - emits when was received a new response of Asterisk;
disconnect - emits when client was disconnected;
reconnection - emits when client tries reconnect to Asterisk;
internalError - emit when happens something very bad. Like a disconnection from Asterisk and etc;
${eventName} - emits when was received event with name eventName of Asterisk and parameter emitEventsByTypes was set to true. See example 5;
${resp_ActionID} - emits when was received response with ActionID of Asterisk and parameter emitResponsesById was set to true. See example 5.

Client's parameters

Default values:

{
    reconnect: false,
    maxAttemptsCount: 30,
    attemptsDelay: 1000,
    keepAlive: false,
    keepAliveDelay: 1000,
    emitEventsByTypes: true,
    eventTypeToLowerCase: false,
    emitResponsesById: true,
    dontDeleteSpecActionId: false,
    addTime: false,
    eventFilter: null  // filter disabled
}

reconnect - auto reconnection;
maxAttemptsCount - max count of attempts when client tries to reconnect to Asterisk;
attemptsDelay - delay (ms) between attempts of reconnection;
keepAlive - when is true, client send Action: Ping to Asterisk automatic every minute;
keepAliveDelay - delay (ms) between keep-alive actions, when parameter keepAlive was set to true;
emitEventsByTypes - when is true, client will emit events by names. See example 5;
eventTypeToLowerCase - when is true, client will emit events by names in lower case. Uses with emitEventsByTypes;
emitResponsesById - when is true and data package of action has ActionID field, client will emit responses by resp_ActionID. See example 5;
dontDeleteSpecActionId - when is true, client will not hide generated ActionID field in responses;
addTime - when is true, client will be add into events and responses field $time with value equal to ms-timestamp;
eventFilter - object, array or Set with names of events, which will be ignored by client.

Methods

.connect(username, secret[, options]) - connect to Asterisk. See examples;
.disconnect() - disconnect from Asterisk;
.action(message) - send new action to Asterisk;
.write(message) - alias of action method;
.send(message) - alias of action method;
.option(name[, value]) - get or set option of client;
.options([newOptions]) - get or set all options of client.

Properties

Getters

lastEvent - last event, which was receive from Asterisk;
lastResponse - last response which was receive from Asterisk;
isConnected - status of current connection to Asterisk;
lastAction - last action data which was transmitted to Asterisk;
connection - get current amiConnection.

Tests

Tests require Mocha.

mocha ./tests

or with npm

npm test

Test coverage with Istanbul

npm run coverage

License

Licensed under the MIT License