This section cover the preferred way to extend the functionalities of a Wazo server. There are many extension point in Wazo, all of them can be used in combination to add complete features to you favorite PBX.

What is a plugin

A plugin is a set of additions made to a custom Wazo installation to add a new functionality.

What can be done with a plugin

Wazo plugins allow a third party to add almost anything to Wazo. Most of our services have extension points that can be used together to create a complete feature as a plugin.

Here’s a non exhaustive list of what can be done with plugins

  • Add configuration files to wazo services in /etc/*/conf.d/

  • Add configuration files and dialplan files to Asterisk

  • Reload services to complete the installation

  • Extend wazo services using the available extension points

    • wazo-auth
    • xivo-confd
    • xivo-confgend
    • xivo-ctid-ng
    • xivo-dird

Creating a plugin

A plugin has the following structure:

  • wazo/plugin.yml
  • wazo/rules


The plugin.yml file contains all the metadata of plugin. It should contains the following fields:

  • description: The description of the plugin
  • name: The name of the plugin
  • namespace: An identifier for the author of the plugin
  • version: The version of the plugin
  • plugin_format_version: The version of the plugin specification implemented by this plugin.
  • depends: Other plugins which this plugin depends on
  • debian_depends: Debian packages which this plugin depends on


name: foobar
namespace: foocorp
version: 0.0.1
description: This plugin adds some foo to your Wazo
plugin_format_version: 1
  - name: foobaz
    namespace: foocorp
  - name: admin-ui-context
    namespace: official
    version: 0.0.1
  - golang-go


The rules file is an executable that will accept the following commands

  • build
  • package
  • install
  • uninstall

Hello World

This example will create a plugin that adds an extension ***42 that says Hello World when called.


namespace: demo
name: helloworld
description: Adds the extension "***42" to you dialplan to greet users
version: 0.0.1
plugin_format_version: 0



case "$1" in
        mkdir -p ${pkgdir}/etc/asterisk/extensions_extra.d
        cp helloworld.conf ${pkgdir}/etc/asterisk/extensions_extra.d/
        asterisk -x 'dialplan reload'
        echo "$0 called with unknown argument '$1'" >&2
        exit 1


exten = ***42,1,Playback(hello-world)
same = n,Return()

Plugin format version

0 (default)

A plugin in version 0 should implement the following requirements:

  • an executable name wazo/rules that returns 0 on success for the following commands:
    • build
    • package
    • install
    • uninstall

rules commands

The build command is used to compile or generate files that will be included in the package.

The package command is used to copy all files required by the plugin in the <pkgdir> directory.

The pkgdir environment variable holds the prefix that will be used to build the package. If the plugin needs to install a file in /etc/foo/bar do the following commands

mkdir -p ${pkgdir}/etc/foo
cp bar ${pkgdir}/etc/foo/bar
The install command is used at the end of the installation to execute instructions that are usually not related to the file system. It will be used as the postinst of the generated debian package.
The uninstall command is used before the debian package is removed. It will be used as the prerm of the generated debian package.
postrm (added in version 1)
The postrm command is used at the end of the debian package removal. It will be used as the postrm of the generated debian package.