active_mailbox

ActiveMailbox

ActiveMailbox provides a simple API and command line utility to work with voicemail boxes and voicemails generated by Asterisk.

Command line usage via active_mailbox

ActiveMailbox includes a command line tool which administrators can use to perform maintenance on a user's mailbox.

The command takes three arguments: the action (OPTION), the context defined in voicemail.conf (CONTEXT), and the user's phone number (MAILBOX)

Usage: active_mailbox [OPTION] MAILBOX

Mailbox Options:
        --context                    Look for [MAILBOX] in [CONTEXT]
        --delete                     Delete [MAILBOX] and all messages
        --sort                       Sort messages in [MAILBOX] (recursive)

Cleanup Options:
        --clean-ghosts               Cleanup 'ghost' messages
        --clean-stale                Cleanup messages older than 30 days
        --clean-mp3s                 Cleanup [MAILBOX]/.mp3 directory
        --purge                      Remove all messages, but leave [MAILBOX] folders intact

Greeting Options:
        --delete-temp                Delete [MAILBOX]/temp.wav
        --delete-unavail             Delete [MAILBOX]/unavail.wav
        --delete-busy                Delete [MAILBOX]/busy.wav

General Options:
    -h, --help                       Show this message
    -v, --version                    Show version

Example Command line usage

Delete unavailable greeting

active_mailbox --delete-unavail 15183332220

Delete temp greeting

active_mailbox --delete-temp 15183332220

Purge mailbox (deletes all messages, leaves folders intact)

active_mailbox --purge 15183332220

Delete messages older than 30 days

active_mailbox --clean-stale 15183332220

Delete mailbox

active_mailbox --delete 15183332222

Delete 'ghost' messages

Ghost voicemails happen if a message's txt file exists, but the corresponding wav file does not. Example:

tree 518/15183332225/INBOX
    518/15183332225/INBOX
    |-- msg0000.txt
    |-- msg0000.wav
    `-- msg0002.txt

Run active_mailbox --clean-ghosts to clear the offending txt files.

active_mailbox --clean-ghosts 518 15183332220

Observe the results:

tree 518/15183332225/INBOX
    518/15183332225/INBOX
    |-- msg0000.txt
    `-- msg0000.wav

Sorting

If voicemails are manually deleted, the INBOX order can be out of sync, as depicted below:

tree 518/15183332225/INBOX
    518/15183332225/INBOX
    |-- msg0000.txt
    |-- msg0000.wav
    |-- msg0002.txt
    |-- msg0002.wav
    |-- msg0006.txt
    |-- msg0006.wav
    |-- msg0009.txt
    `-- msg0009.wav

Sort the messages so they play correctly in Asterisk using active_mailbox --sort:

active_mailbox --sort 15183332225

Messages are renamed in INBOX after sorting

tree 518/15183332225/INBOX
    518/15183332225/INBOX
    |-- msg0000.txt
    |-- msg0000.wav
    |-- msg0001.txt
    |-- msg0001.wav
    |-- msg0002.txt
    |-- msg0002.wav
    |-- msg0003.txt
    `-- msg0003.wav

Library Usage

ActiveMailbox can also be used in ruby scripts to work with mailboxes and voicemail messages.

Working with mailboxes

# Create a mailbox object
mailbox = ActiveMailbox::Mailbox.find('office_a', '1234')

# Destroy mailbox and all messages/greetings
mailbox.destroy!

# Determine the greeting Asterisk will playback
mailbox.current_greeting

# Destroy ``unavail.wav``
mailbox.destroy_greeting!

# Destroy ``temp.wav``
mailbox.destroy_temp!

# A Hash of the mailbox's messages
#
# Keys are the subdirectory, lowercased, as
# a symbol. Eg: INBOX = :inbox, Old = :old
#
# Values are arrays of Message objects
mailbox.folders

# Fetch array of messages in :inbox
inbox = mailbox.folders[:inbox]

# Or some sugar
inbox = mailbox.inbox

# Or :old
mailbox.folders[:old]
mailbox.old

Working with messages

# Set mailbox
mailbox = ActiveMailbox::Mailbox.find('office_a', '1234')

# Get first message in INBOX
vm = mailbox.inbox.first

# Path to Asterisk generated msg####.txt
vm.txt

# Path to Asterisk generated msg####.wav
vm.wav

# Caller ID name
vm.callerid_name

# Caller ID number
vm.callerid_number

# Message duration (in seconds)
vm.duration

# Delete this message
# Deletes wav, txt, mp3, xml files
vm.destroy!

Notes

If Asterisk does not keep voicemail in /var/spool/asterisk/voicemail on this server, add the following to ~/.bashrc (or the appropriate shell config file):

export ASTERISK_VOICEMAIL_ROOT='/my/alternate/voicemail/path'

Note that you can specify this as an ENV variable when running the active_mailbox executable.

ASTERISK_VOICEMAIL_ROOT='/root' active_mailbox [OPTION] MAILBOX

Development

ActiveMailbox is still in development, as such, don't use it yet unless you're brave. Then again, if you're using Asterisk, you're already a cowboy so have fun!

License

MIT License, see LICENSE.