search

marcelog / Nami

Asterisk manager interface (ami) client for nodejs
http://marcelog.github.com/Nami
Apache License 2.0
99 stars 59 forks source link
ami asterisk javascript nodejs

readme

Click here to lend your support to: Nami and make a donation at pledgie.com !

Introduction

For API and docs, check out the homepage at http://marcelog.github.com/Nami

You can also download the distribution and doc from the CI server, at: http://ci.marcelog.name:8080/view/NodeJS/

A very similar, PHP alternative, is available at http://marcelog.github.com/PAMI An Erlang port is available at https://github.com/marcelog/erlami

Nami by itself is just a library that allows your nodejs code to communicate to an Asterisk Manager Interface (AMI). However, it includes a full application useful to monitor an asterisk installation.

You will be able to login, receive asynchronous events, and send actions (also, asynchronously receiving the according response with their optional related events).

This is supported by the Nami class (er.. function) which inherits from EventEmitter, so your application is able to subscribe to the interesting nami events.

Requirements

Events used in Nami

Internal Nami events

Installation

$ npm install nami

-or- Download it from this repo :)

Configuration

Nami expects a configuration object, very much like this:

var namiConfig = {
    host: "amihost",
    port: 5038,
    username: "admin",
    secret: "secret"
};

Quickstart

$ mkdir testnami
$ cd testnami
$ npm install nami
var nami = new (require("nami").Nami)(namiConfig);
nami.on('namiEvent', function (event) { });
nami.on('namiEventDial', function (event) { });
nami.on('namiEventVarSet', function (event) { });
nami.on('namiEventHangup', function (event) { });
process.on('SIGINT', function () {
    nami.close();
    process.exit();
});
nami.on('namiConnected', function (event) {
    nami.send(new namiLib.Actions.CoreShowChannelsAction(), function(response){
        console.log(' ---- Response: ' + util.inspect(response));
    });
});
nami.open();

Adding variables to actions

Use the property 'variables' in the actions:

var action = new namiLib.Actions.Status();
action.variables = {
    'var1': 'val1'
};
nami.send(action, function(response) {
    ...
});

A Better example

See src/index.js for a better example (including how to reconnect when the current connection closes).

That's about it.

Using logger other than console

Nami config may contain an optional attribute 'logger'. If it exists, it will be used instead of console:

namiConfig.logger = require('log4js').getLogger('Nami.Core');
var nami = new (require("nami").Nami)(namiConfig);

Viable options: https://github.com/nomiddlename/log4js-node https://github.com/trentm/node-bunyan

Logger may be anything that can be looks like:

logger = {
    error: function(message) {},
    warn : function(message) {},
    info : function(message) {},
    debug: function(message) {},
}

Controlling the loglevel

If you are using your own logger (i.e: overriding the logger property of the Nami client), you should check the documentation for it and apply the needed changes or configuration accordingly.

If you are using the default Nami logger, you can set the property logLevel of the Nami client to one of the following values:

Multiple server support

See this gist for an example of how to connect to multiple asterisk boxes.

Supported Actions (Check the api for details)

Thanks to