Skip to main content

Track channels through Asterisk Management Interface (AMI)

Project description


Cacofonisk is a framework that connects to the Asterisk PBX, listens to events on the Asterisk Management Interface (AMI) and tracks the status of calls currently in progress in Asterisk.

Cacofonisk takes a stream of AMI events as input and uses these to keep track of the channels currently active in Asterisk and how they are related. When something interesting happens to one of the channels, it will call a method on a call state Reporter with interesting information about the call, like who is in the call, and a unique identifier.

This data can then be used to send webhooks regarding a call, to notify a person who is being called, or to log calls being performed.


This product is actively being developed and used at VoIPGRID.



  • Python >= 3.4
  • Panoramisk 1.x
  • Asterisk >= 12


Cacofonisk is available on Pypi so you can easily install it with pip:

$ pip install cacofonisk

To install the dependencies from source:

$ python3 install


To run Cacofonisk, you will need two things: a Runner and a Reporter.

A Runner is a class which is responsible for passing AMI events to the Cacofonisk. Two runners are included: an AmiRunner (which connects to the Asterisk Management Interface) and a FileRunner (which imports AMI events from a JSON file).

A Reporter is a class which takes the interesting data from Cacofonisk and does awesome things with it. You can find various Reporters in the examples folder.

To create your own reporter, you can extend the BaseReporter class and implement your own event handlers, like so:

from cacofonisk import AmiRunner, BaseReporter

class ReportAllTheThings(BaseReporter):

    def on_b_dial(self, caller, targets):
        target_channels = [ for target in targets]
        caller_number = caller.caller_id.num
        print("{} is now calling {}".format(
            caller_number, ', '.join(target_channels),

    def on_up(self, caller, target):
        target_number = target.caller_id.num
        caller_number = caller.caller_id.num
        print("{} is now in conversation with {}".format(caller_number, target_number))

    def on_hangup(self, caller, reason):
        caller_number = caller.caller_id.num
        print("{} is no longer calling (reason: {})".format(caller_number, reason))

reporter = ReportAllTheThings()
runner = AmiRunner(['tcp://username:password@'], reporter)

This reporter can then be passed to a Runner of your choice to process AMI events.

For more information about the parameters of the reporter, please see the docs in BaseReporter.

You can also listen for UserEvents using the on_user_event function. This can be used to pass additional data from Asterisk to your Cacofonisk application.

Running the tests

To run the test suite:

$ python3 -m unittest


See the file on how to contribute to this project.


See the file for a list of contributors to the project.



The changelog can be found in the file.

In progress

No features are currently in progress.


No features are currently scheduled. Have great ideas? Please don't hesitate to share them!

Get in touch with a developer

If you want to report an issue see the file for more info.

We will be happy to answer your other questions at


Cacofonisk is made available under the MIT license. See the LICENSE file for more info.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for cacofonisk, version 0.7.2
Filename, size File type Python version Upload date Hashes
Filename, size cacofonisk-0.7.2-py3-none-any.whl (37.9 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size cacofonisk-0.7.2.tar.gz (29.9 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page