---
layout: page
title: "Asterisk Voicemail Server Installation"
description: "Instructions on how to integrate your existing Asterisk voicemail within Home Assistant."
date: 2017-06-30 18:30
sidebar: true
comments: false
sharing: true
footer: true
---

Asterisk Voicemail integration allows Home Assistant to view, listen to and delete voicemails from a Asterisk voicemail mailbox.

There are two components to the integration:

- A server that runs on the Asterisk PBX host and communicates over an open port.
- A client which can request information from the server.

Both parts are necessary for Asterisk voicemail integration.

The server installation is documented below. The client is [integrated inside Home Assistant](/components/asterisk_mbox)

<p class='note'>
Currently this module can only monitor a single Asterisk PBX mailbox.
</p>

### {% linkable_title Prerequisites %}

Before beginning make sure that you have the following:

- A functional Asterisk PBX setup which is using the default `voicemail` application.
- Both Home Assistant and Asterisk PBX running on the same LAN (or the same server).
- The Asterisk PBX server has Python 3.5 or newer installed.
- Administrator access on the Asterisk PBX (for python module installation).
- Account access to the `asterisk` user that runs the Asterisk PBX software.

### {% linkable_title Installation %}

1. Apply for a Google API key to enable speech-transcription services

2. Install the `asterisk_mbox_server` python module:

   ```bash
   $ pip3 install asterisk_mbox_server
   ```

3. Create a configuration file for the server

   As the `asterisk` user create an `asterisk_mbox.ini` file. You can place this in any directory you choose, but the recommended location is `/etc/asterisk/asterisk_mbox.ini`.

   ```ini
   [default]
   host = IP_ADDRESS 
   port = PORT
   password = PASSWORD
   mbox_path = PATH_TO_VOICEMAIL_FILES
   cache_file = PATH_TO_CACHE_FILE
   google_key = GOOGLE_API_KEY
   cdr = mysql+pymysql://<mysql-user>:<mysql-password>@localhost/asterisk/cdr

   ```

   - **host** (*Optional*): The IP address to listen on for client requests. This defaults to all IP addresses on the server. To listen only locally, choose `127.0.0.1`
   - **port** (*Optional*): The port to listen on for client requests. Defaults to 12345.
   - **password** (*Required*): A password shared between client and server.  Use only alpha-numeric characters and spaces
   - **mbox\_path** (*Required*): The path to the storage location of mailbox files. This is typically `/var/spool/asterisk/voicemail/default/<mailbox>/`
   - **cache\_file** (*Required*): A fully-qualified path to a file that can be written by the server containing transcriptions of voicemails. Example: `/var/spool/asterisk/transcription.cache`
   - **google\_key** (*Required*): Your 40 characters Google API key.
   - **cdr** (*Optional*): Where to find CDR data.  Supports various SQL databases as well as a file log.  Configuring the CDR will enable the `asterisk_cdr` platfom.

   Once complete, ensure this file is only accessible by the Asterisk user:

   ```bash
   $ sudo chown asterisk:asterisk /etc/asterisk/asterisk_mbox.ini
   $ sudo chmod 600 /etc/asterisk/asterisk_mbox.ini
   ```
4. Interactively start the server to verify it is functioning

   ```bash
   $ sudo -u asterisk asterisk_mbox_server -v --cfg /etc/asterisk/asterisk_mbox.ini
   ```

   Now complete the [Home Assistant configuration](/components/asterisk_mbox) and verify that Home Assistant can communicate with the server

   You can use `Ctrl-c` to terminate the server when done testing

5. Configure the server to start automatically

   Copy the following code into `/etc/systemd/system/asterisk_mbox.service`:
   ```ini
   [Unit]
   Description=Asterisk PBX voicemail server for Home Assistant
   Wants=network.target
   After=network.target

   [Service]
   Type=simple
   User=asterisk
   Group=asterisk
   ExecStart=/usr/local/bin/asterisk_mbox_server -cfg /etc/asterisk/asterisk_mbox.ini
   Restart=on-failure

   [Install]
   WantedBy=multi-user.target
   ```

<p class='note'>
This assumes that your Asterisk PBX server is using `systemd` for init handling. If not, you will need to create the appropriate configuration files yourself.
</p>