Asterisk Voicemail Server Installation

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 inormation from the server.

Both parts are necessary for Asterisk voicemail integration.

The server installation is documented below. The client is integrated inside Home Assistant

Currently this module can only monitor a single Asterisk PBX mailbox. Multiple mailbox support is planned for the future

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.4 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

Installation

Apply for a Google API key to enable speech-transcription services
Install the asterisk_mbox_server python module:
```
$ pip3 install asterisk_mbox_server
```
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 rommended location is /etc/asterisk/asterisk_mbox.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
```
- 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. (default: 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 thht can be written by the server containing transcriptions of voicemails. Example: /var/spool/asterisk/transcription.cache
- google_key (Required): Your 40 character Google API key
Once complete, ensure this file is only accessible by the asterisk user:
```
$ sudo chown asterisk:asterisk /etc/asterisk/asterisk_mbox.ini
$ sudo chmod 600 /etc/asterisk/asterisk_mbox.ini
```
Interactively start the server to verify it is functioning
```
$ sudo -u asterisk asterisk_mbox_server -v --cfg /etc/asterisk/asterisk_mbox.ini
```
Now complete the Home Assistant configuration and verify that Home Assistant can communicate with the server

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

Configure the server to start automatically

Copy the following code into /etc/systemd/system/asterisk_mbox.service:

[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

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.