Asterisk as a Voicemail Server
The following table summarizes the steps to integrate SIP Server with Asterisk to support the Voicemail solution.
Related Procedures and Actions
1. Configure the SIP Server Application configuration object.
2. Configure DNs, Agent Logins, and Agent Groups in the SIP Server Switch object to use voicemail boxes.
3. Configure Asterisk using the GVMA utility.
The GVMA utility is used to collect all GVM-options from the Switch objects in the Configuration Layer and propagate these options into the Asterisk configuration. Some manual Asterisk configuration may be required. See Configuring Asterisk.
Configuring a SIP Server Application object
- Set the MWI mode:
In the SIP Server Application object, set the mwi-mode option to REGISTER or SUBSCRIBE. This is the SIP method that SIP Server uses to utilize the MWI interface.
- With a value of SUBSCRIBE (default), SIP Server activates SIP subscriptions for all voicemail box owners as configured by other mwi-<xxx> options.
- With a value of REGISTER, SIP Server activates MWI functionality using the REGISTER SIP message.
Set the mwi-domain option to the domain name, which SIP Server should send to Asterisk in the MWI REGISTER or SUBSCRIBE requests. This option must be synchronized with the Asterisk settings. But in the basic configuration it can be set to the Asterisk hostname or IP address.
- Configure SIP Server access to Asterisk:
In the SIP Server Application object, set the following configuration options:
- mwi-host: Enter the host name or IP address where Asterisk runs.
- mwi-port: Enter the port on Asterisk to listen to the SIP messages.
SIP Server sends MWI-related REGISTER and SUBSCRIBE requests to the address specified by these two options.
- Select the types of voicemail boxes to use:
In the SIP Server Application object, set the parameters corresponding to the voicemail box types to be used in the system to true to activate a support of the voicemail boxes of this type. Multiple voicemail box types can be enabled simultaneously.
- mwi-extension-enable--For a voicemail box of type Extension
- mwi-agent-enable--For a voicemail box of type Agent
- mwi-group-enable--For a voicemail box of type Agent Group
Configuring Configuration Layer Objects
Genesys provides the Genesys Voicemail Adapter (GVMA) utility, which reads the configuration related to the Voicemail solution from the Configuration Layer. The GVMA utility uses this information to modify the Asterisk configuration accordingly. All Configuration Layer objects that you will associate with the Asterisk-hosted voicemail boxes must be supplied with the GVM options, which provide necessary information for the GVMA utility.
There are three types of configuration objects that can be associated with the voicemail boxes:
- Agent Login
- Agent Groups
A DN object can be associated only with the Extension voicemail box.
An Agent Login object can be associated with two types of voicemail boxes at the same time:
- Agent voicemail box
- Agent Group voicemail box
An Agent Groups object can be associated with the Agent Group voicemail box only.
GVM Configuration Options
You specify GVM configuration options in the TServer section on the Annex tab of the following three configuration objects:
- Agent Login
- Agent Group
You can use all GVM options in all objects with one exception the gvm_group_mailbox option, which can appear only in the Agent Login object. A full set of GVM options, which you can use to configure objects, is provided below:
- gvm_mailbox: This option is used in two ways:
- The GVMA utility uses this option as the name of the voicemail box it creates on Asterisk for the DN, Agent Login, and Agent Group objects.
- SIP Server uses the value of this option to activate the MWI subscription for a voicemail box created for the DN and Agent Login objects. SIP Server compiles an object name for the MWI subscription as shown in the following table:
Example of Compiled Object Names for the MWI Subscription
Configuration Layer Objects
MWI Subscription Name
The MWI subscription name is sent in the SIP SUBSCRIBE message to Asterisk to activate the MWI subscription. See more information about this option in Configuring the Voicemail Boxes for Agent Groups.
- gvm_group_mailbox: This option can be specified only in Agent Login objects. SIP Server uses the value of this option to compile the MWI subscription name for the Agent Group voicemail box. For example, if this option is set to 1000, then SIP Server sends a SUBSCRIBE message to Asterisk to activate the MWI subscription to the object gvm-g-1000. See more information about this option in Configuring the Voicemail Boxes for Agent Groups.
- gvm_mailbox_context: This option is defined only if the voicemail box already exists for this configuration object and a new one must not be created. In this case, the option contains the name of the Voicemail context in the voicemail.conf file where the voicemail box resides.
- gvm_name: This option specifies the owner's name associated with the voicemail box.
- gvm_password: This option specifies the voicemail box password.
- gvm_email: This option specifies the e-mail associated with the voicemail box. Asterisk can be configured to send Voicemail notifications to this e-mail address.
- gvm_pager_email: This option specifies the pager e-mail associated with the voicemail box.
- gvm_options: This option specifies a list of voicemail box options separated by a pipe (|) symbol. For more information, see Asterisk documentation.
Voicemail Boxes Created by the GVMA Utility
The GVMA utility scans the following objects to decide if it should create new voicemail boxes for them in the Asterisk configuration:
- All DNs for a switch specified in the GVMA configuration file.
- All Agent Logins for a switch specified in the GVMA configuration file.
- All Agent Groups for a tenant specified in the configuration file.
A new voicemail box, which does not have the GVM option gvm_mailbox_context specified, is created for all DNs. The voicemail box name is set to the value of the gvm_mailbox option if it is specified for this DN. If this option is undefined, then the voicemail box is created with the name of the DN. The DN name is also used as the default value of the gvm_password and gvm_name options.
A new voicemail box is created for the Agent Login or Agent Group object only if the gvm_mailbox option is specified for this object in the Configuration Layer. If there is no such option, a voicemail box is not created.
Configuring the Voicemail Boxes for Agent Groups
The voicemail box configuration for an Agent Group should be provided in the TServer section on the Annex tab of the corresponding Agent Group object. This information is used by the GVMA utility, which creates a MWI subscription object for SIP Server in the Asterisk configuration. The GVMA utility monitors either the existing voicemail box or the one specifically created for the Agent Group.
SIP Server does not read information about Agent Groups from the Configuration Layer. So, the configuration information specified in the Agent Group objects is not available for SIP Server. It also means that SIP Server does not have information about how agents are organized into the Agent Groups.
SIP Server uses the GVM option gvm_group_mailbox specified in the TServer section on the Annex tab of the Agent Login object to associate an agent with the Agent Group.
SIP Server analyzes two GVM options specified for an agent when this agent logs in:
If the gvm_mailbox is specified, SIP Server activates the MWI subscription to a voicemail box for this agent. If the gvm_group_mailbox is defined for this agent, SIP Server initiates the MWI subscription to the Agent Group voicemail box. In this scenario, one agent has multiple MWI subscriptions active. This agent will receive Voicemail-related notifications for both personal Agent voicemail boxes and Agent Group voicemail boxes.
Configuring Agents Registered on Asterisk or on SIP Server
There are two possible scenarios to configure GVM options for a corresponding configuration object:
- A voicemail box is already created for this object.
- A new voicemail box should be created for this object.
The first scenario occurs when SIP Server is added to the existing Asterisk installation in which agents register directly on Asterisk and already have the voicemail boxes configured for them. In this case, it is only required for SIP Server to monitor existing voicemail boxes to provide appropriate notifications to the T-Library clients.
The second scenario takes place when Asterisk is added to the SIP Server installation. All agents register on SIP Server and all of them need new voicemail boxes created. It is also possible to build a system with both types of agents.
The GVMA utility uses the gvm_mailbox_context option to differentiate these two scenarios. If this option is not specified in the corresponding object, then GVMA creates a new mail box in one of the GVMA default contexts (GVMA_DN / GVMA_AGENT / GVMA_AGENTGROUP). If this option is specified, then GVMA does not create a new voicemail box for this configuration object, and it uses the specified context in the voicemail box option of the sip.conf file.
Configuring Access to Voicemail Boxes for the Agents Registered on SIP Server
SIP Server supports three types of voicemail boxes:
- Agent Login
- Agent Group
The GVMA utility used for the Asterisk configuration creates voicemail boxes in three different contexts in the voicemail.conf Asterisk configuration file:
- GVMA_DN: The voicemail boxes are associated with Extensions.
- GVMA_AGENT: The voicemail boxes are associated with Agent Logins.
- GVMA_AGENTGROUP: The voicemail boxes are associated with Agent Groups.
Correspondingly, three different prefixes (wild cards) are configured in the extensions.conf configuration file to reach voicemail boxes in three contexts. To utilize this configuration on the Asterisk side there should be one or several trunks configured in the SIP Server Switch configuration object to send all voicemail calls to Asterisk. Prefixes defined for these trunks should match the wild cards used on Asterisk to reach different voicemail contexts. Configured prefixes will be supplied as options for the GVMA utility later.
To access a voicemail box with this configuration, agents need to dial a prefix corresponding to a voicemail box type, followed by the voicemail box number.