SIP Server and Asterisk Integration Overview
Asterisk integrated with SIP Server can function in three different roles:
- As a PBX with a business call routing capability.
- Asterisk is configured to send business calls to SIP Server to engage a Genesys routing solution. SIP Server uses the routing results to forward the call to the selected agent.
- As a voicemail server.
- SIP Server uses Asterisk as a voicemail server. Unanswered calls are forwarded to Asterisk to record the voice messages. Contact center agents receive indication on their T-Library agent desktops about new voice messages waiting in their voicemail box. Agents can access and manage their voicemail boxes hosted on Asterisk.
- As a media server.
- SIP Server uses Asterisk as a Media Server. Asterisk is engaged in the call to perform one of the following functions:
- Call recording
- Announcement or music playing
- DTMF digits collection
When SIP Server is integrated with Outbound Contact Server (OCS), the following configuration changes on Asterisk might be recommended. The notifyringing parameter should be set to no in order to avoid notifications sent by Asterisk when an agent’s extension goes to ringing state. This parameter can only be set globally in the [general] section of the sip.conf file.
Asterisk with a Business Call Routing Capability
The SIP Server - Asterisk Deployment Architecture figure depicts a sample deployment architecture of SIP Server with Asterisk, in which:
- Asterisk is connected to the network via a SIP gateway.
- The agent endpoint is registered on Asterisk.
- The agent endpoint is associated with a T-Library desktop application.
Integration with the Asterisk switch relies on the SIP presence subscription from SIP Server. For any call handled by the agent endpoint, Asterisk is requested to provide a notification about the status change for that endpoint. SIP Server uses those notifications to synchronize an agent state visible to all Genesys T-Library clients with the actual state of this agent. The business call routing solution that is built on these integration principles involves SIP Server to handle the business calls only. Private calls are processed locally on Asterisk. Agent statuses are reported to SIP Server for all call types, because they are used to identify the agents' availability for the Genesys Routing Solution.
All figures in this topic depicting Stream Manager refer to the Genesys Stream Manager. This component, when working together with SIP Server, provides different kinds of media services, such as ring-back, music-on-hold, DTMF digit collection, and others. You can also configure Asterisk to work as a media server for SIP Server. For information about architectural and configuration details of this solution, see Asterisk as a Media Server.
An Asterisk dialing plan can be set up in such a way that private calls (direct calls to an agent, for example) are not forwarded to SIP Server. Instead, only the notification about the busy status of the endpoint is passed to SIP Server. SIP Server uses this status change notification to set the endpoint DN to a busy state (EventAgentNotReady), so that the rest of the Genesys suite will not consider that DN available for the routing of contact center calls.
The following figure illustrates the processing of private calls.
Contact Center Calls
In the same way that you can set up an Asterisk dialing plan to bypass SIP Server for private calls, you can write rules so that Asterisk connects contact center calls (typically, calls to the service number of the company) to SIP Server. After that, SIP Server triggers a strategy for Universal Routing Server (URS) to process this type of call. Eventually, an agent DN is selected to handle the customer call and SIP Server initiates a new dialog to Asterisk for the selected endpoint. Finally, Asterisk delivers the call to the agent endpoint.
This mechanism creates a signaling loop inside SIP Server, which is then in charge of maintaining the inbound leg from Asterisk (customer leg) with the outbound leg to Asterisk (agent leg).
Note: From the Asterisk perspective, the two legs are two completely separate calls. Correlation is performed at the SIP Server level.
By staying in the signaling path, SIP Server detects any change in call status, and can therefore produce call-related events (EventRinging, EventEstablished, EventReleased, and so on).
Any call control operation from the agent must be performed using a third-party call control (3pcc) procedure. In other words, the agent desktop must be used for any call control operation (besides the answer call operation). This includes, but is not limited to, hold, transfer, and conference requests.
The following figure illustrates the processing of contact center calls.
At startup, SIP Server sends SUBSCRIBE messages to the Asterisk switch, which notifies about changes in the endpoints' status. The Asterisk switch sends NOTIFY messages to SIP Server to report the endpoints' status. See the following figure.
If an endpoint is not yet registered, the Asterisk switch reports its status as closed. As soon as the endpoint registers, Asterisk sends a NOTIFY message to SIP Server, reporting the status open. See the following figure.
For private calls, the Asterisk dialing plan is set up in such a way that the call is sent directly to the endpoint. Asterisk notifies SIP Server about the call activity on that particular endpoint. In this case, SIP Server generates EventAgentNotReady, which reports the overall agent status as unavailable for contact center calls. (See the Private Call Processing figure.)
SIP Server generates only agent-related TEvents for the private Asterisk calls—for example, EventAgentReady and EventAgentNotReady. Call-related events"such as EventRinging, EventEstablished, and so on--are not generated for private calls, because SIP Server is not involved in the processing of private calls.
As soon as the call is released at the endpoint, Asterisk notifies SIP Server, which then generates an EventAgentReady message. The agent is then considered available for contact center calls.
Note: The mechanism for private outbound call processing is exactly the same. SIP Server receives the NOTIFY messages sent by Asterisk.
Contact Center Calls
Inbound Calls to SIP Server: Inbound contact center calls are programmed within the Asterisk dialing plan to be directed to SIP Server. In this case, the call arrives at a Routing Point, and URS is triggered. You can request a call treatment (using the TApplyTreatment request) to play announcement or music. If Stream Manager is configured to provide a treatment functionality, SIP Server connects a caller to Stream Manager to listen to the treatment while waiting for an agent to become available. See the following figure.
Whenever the agent becomes ready, SIP Server receives a TRouteCall request to the targeted agent endpoint. Because this endpoint is configured to point to Asterisk, SIP Server then initiates a new dialog with Asterisk to engage the agent. Asterisk forwards the call to the specified endpoint and reports to SIP Server the call activity on that endpoint with a NOTIFY message (EventAgentNotReady). When the call is answered, Stream Manager is disconnected, and the original SIP dialog is renegotiated between SIP Sever and Asterisk.
Because SIP Server is in the signaling path for contact center calls, it generates all call-related events (EventRinging, EventEstablished, and so on) for the agent's DN. See the following figure.
Furthermore, when the call is released, SIP Server also generates EventReleased, and Asterisk notifies SIP Server with a NOTIFY message (EventAgentReady). See the following figure.
Inbound Calls to Extensions: Inbound contact center calls, and manual internal first-party call control (1pcc) calls that are directed to extensions, are not visible to SIP Server; as a result, you cannot make third-party call control (3pcc) calls for them. Only inbound calls that are directed to Routing Points on SIP Server, and manual internal calls, which go via Routing Points can be seen by SIP Server; as a result, 3pcc calls can be made for them.
Outbound Calls: An outbound call that is contact-center-related (for example, a call back to a customer) must be performed using 3pcc operations. This ensures that SIP Server creates and controls the SIP dialogs on behalf of the agent endpoint. SIP Server uses the call flow 1 described in RFC 3725 to create a call initiated from the agent's T-Library client using the TMakeCall request.
An agent initiates the outbound call by sending the TMakeCall request from the T-Library client to SIP Server. SIP Server attempts to engage the agent by sending the INVITE message to this agent endpoint (via Asterisk).
Note: If the phone is not configured with auto-answer, the agent must manually answer the call. This is the only manual action that is required for contact center calls.
If Stream Manager is configured to provide treatments, then SIP Server connects the agent to Stream Manager to listen to a ringback tone while establishing a connection to the outbound call destination. See the following figure.
SIP Server contacts the requested destination number. After the destination answers the call, SIP Server discontinues the ringback tone (by sending the BYE message to Stream Manager) and renegotiates with the agent endpoint (via Asterisk), so that the media stream is connected between the agent and the customer. See the following figure.
Although disconnection would work if it were initiated directly from the agent endpoint, it is good practice to always use a desktop application to perform any actions related to contact center calls. Therefore, the disconnection is requested by sending the TReleaseCall request to SIP Server.
SIP Server manages two dialogs: one for the agent and another for the customer. It sends the BYE message to both of them, and the call is eventually disconnected. See the following figure.
Asterisk as a Voicemail Server
Asterisk can provide the voicemail server functionality. A stand-alone Asterisk solution allows all agents registered on Asterisk to use multiple voicemail boxes. SIP Server integration with Asterisk adds several new voice-mail-related features to the standard Asterisk set:
- Agents registered on SIP Server (an agent VOIP phone sends the SIP REGISTER message to SIP Server) can use voicemail boxes hosted on Asterisk.
- All agents (registered on Asterisk or on SIP Server) can receive voicemail notifications on their T-Library client desktops.
- Voicemail boxes can be associated with extensions, agent logins, and agent groups.
Voicemail Boxes For Agents Registered on SIP Server
One or multiple voicemail boxes can be created on Asterisk for the agents registered on SIP Server. All voicemail features configured on Asterisk become available for SIP Server agents. Unanswered calls can be forwarded to the corresponding voicemail box allowing callers to leave a voice message. SIP Server agents can call their voicemail boxes from their VOIP phones to listen to the voice messages and to manage the voicemail box.
Voicemail Notifications Sent to SIP Server T-Library Clients
Genesys contact center agents use T-Library client desktops. If Asterisk is configured as a voicemail server for SIP Server, agents can receive notifications about the new voice messages left in their voicemail boxes on their T-Library client desktops. These notifications also provide information about the number of old and new messages stored in the voicemail box.
Voicemail Boxes Associated with Extensions, Agent Logins, or Agent Groups
SIP Server associates each voicemail box it controls on Asterisk with one of the following configuration objects in the Configuration Layer: Extension, Agent Login, or Agent Group. The voicemail box associated with a corresponding object defines a group of SIP Server T-Library clients to receive voicemail status notifications for a particular voicemail box. Voicemail notifications described in this section are transmitted using the T-Library interface. SIP Server sends messages to its T-Library clients.
If the voicemail box is associated with an extension, then notifications are sent to an agent whose T-Library client is registered to this extension. If the voicemail box is associated with the agent login, then SIP Server sends voicemail notifications to this agent T-Library client. In this case, it does not matter what DN this agent used to log in.
It is also possible to associate a voicemail box with the agent group. If a new voice message is left in such a voicemail box, then all logged in agents associated with this agent group will receive a notification about this message.
The following figure illustrates a general integration schema representing Asterisk configured as a voicemail server for SIP Server.
The figure also shows how voicemail services can be provided for two agents: Agent DN 1000 and Agent DN 2000. Both agents use T-Library desktops connected to SIP Server via the T-Library protocol. Agent DN 1000 has the VOIP phone that is registered on Asterisk. Agent DN 2000 has the VOIP phone that is registered on SIP Server.
Asterisk is configured to fully support all calls made from and to DN 1000. For this purpose, it has a SIP entity  configured in the sip.conf file to represent the agent's phone. It also has a voicemail box configured in some private context [MY_COMPANY] in the Asterisk voicemail.conf configuration file.
SIP Server integration with Asterisk requires adding a new object to the Asterisk configuration to provide the voicemail functionality for the SIP Server agent at DN 2000. A new voicemail box for this agent is created in the [GVM_DN] context of the Asterisk voicemail.conf configuration file.
The Asterisk Message Waiting Indicator (MWI) interface is used to integrate Asterisk as a voicemail server with SIP Server. The MWI interface utilizes the SIP subscription schema. SIP Server subscribes to the message-summary event at Asterisk using the SIP SUBSCRIBE request method:
SUBSCRIBE sip:email@example.com SIP/2.0
CSeq: 1103 SUBSCRIBE
Via: SIP/2.0/UDP 192.168.0.200:5060;branch=z9hG4bK3B
Asterisk sends notifications to SIP Server about the voicemail box status using the SIP NOTIFY message:
NOTIFY sip:firstname.lastname@example.org:5060;mb=1000;dn=1000;tp=2 SIP/2.0
Via: SIP/2.0/UDP 192.168.0.200:5070;branch=z9hG4bK219f391e
From: "asterisk" <sip:email@example.com:5070>;tag=as13d3077a
CSeq: 102 NOTIFY
User-Agent: Asterisk PBX
SIP Server generates the EventUserEvent message based on this notification and sends it to the T-Library client registered on a DN associated with a particular voicemail box. This is an example of such a T-Library event:
AttributeUserData  00 01 03 00..
'gsipmwi'(list) 'Mailbox 1000'
'NewMessages " 1
"OldMessages " 0
Dedicated SIP objects are created in the sip.conf Asterisk configuration file to support the MWI subscription. These objects are gvm-1000 and gvm-2000 in the Asterisk Configuration as a Voicemail Server figure. The GVM acronym in the object name stands for Genesys Voicemail. These objects are created in Asterisk for MWI subscription purposes only, and no SIP clients are registered on these objects. Both objects have a parameter pointing to a specific Asterisk voicemail box:
SIP Server activates one SIP subscription per voicemail box it needs to monitor. The above configuration guarantees that SIP Server will receive notification on a correct voicemail box when it subscribes to a corresponding GVM object.
MWI Subscription Scope
SIP Server activates one or multiple MWI subscriptions for each voicemail box it needs to monitor. Individual voicemail boxes created for Extensions or Agent Logins are monitored by a single MWI subscription per box. The number of MWI subscriptions activated per Agent Group voicemail box is equal to the number of agents currently logged in to this Agent Group.
SIP Server is designed in the assumption that all extensions have voicemail boxes. So, if MWI monitoring is enabled for the extensions (mwi-extension-enable is set to true), SIP Server at start up attempts to activate MWI subscriptions for all extensions configured in the Configuration Layer. Subscriptions for the Extension-related voicemail boxes are deactivated when SIP Server shuts down.
MWI subscription for Agent Login is when an agent with the corresponding agent ID logs in to SIP Server. SIP Server keeps this subscription active while the agent is logged in and stops it when the agent logs out.
The same MWI subscription logic is applied to the monitoring of voicemail boxes created for the Agent Groups. SIP Server activates MWI subscription for the group when the first agent associated with this group logs in. SIP Server stops the subscription when the last agent of this group logs out.
If, for some reason, a subscription request for any voicemail box type is rejected or times out, SIP Server attempts to activate this subscription again in one minute.
Building a Voicemail Solution
The Voicemail functionality in SIP Server and Asterisk allows you to build multiple Voicemail solutions with different complexity to address different business needs. This section provides examples that show how to build Voicemail solutions. It outlines general architectural ideas that refer to some configuration options only for clarification purposes. For configuration procedures, see the Framework 8.1 SIP Server Deployment Guide.
The easiest approach to a Voicemail solution is to have calls, which are not answered on a DN during a specified timeout, forwarded to the voicemail box associated with this DN (extension). This solution requires that you associate an Asterisk-hosted voicemail box with the DN. A DN object in Configuration Manager should be configured with the following options:
The no-answer-timeout option specifies the time during which the call must be answered. When the no-answer-timeout timer expires and the call is not answered, SIP Server uses the value of option no-answer-overflow to decide how to process the call. If this option contains the name of the voicemail box associated with this DN, then SIP Server sends the call to this voicemail box.
A similar solution can be configured for agents. SIP Server can apply the same algorithm that is used for process unanswered calls for an agent who ignores the DN where the agent logs in. In this case, the Asterisk-hosted voicemail box should be associated with the Agent Login (and not the extension). Also, the no-answer-timeout and no-answer-overflow options should be specified in the Agent Login configuration object.
SIP Server also allows you to use voicemail boxes in business call routing. Usually in those scenarios, calls are controlled by the URS strategy, which attempts to find an appropriate agent to forward the call to. There are many ways to write a URS strategy to utilize a Voicemail solution. For example, if a call is routed to an agent group that does not have any currently available agents, URS can send a call to the voicemail box associated with the Agent Group. In this case, all logged in members of this group will receive a notification about the new message left in the group voicemail box.
SIP Server can also redirect unanswered calls to the voicemail box based on the options configured for the SIP Server Application configuration object. There are two groups of options, which define how SIP Server processes unanswered calls for extensions and for agents:
See the Framework 8.1 SIP Server Deployment Guide for more information about the options.
Asterisk as a Media Server
You can configure Asterisk as a media server for SIP Server. SIP Server can utilize the following services provided by Asterisk:
- Play announcements.
- Collect DTMF digits.
- Organize conferences.
- Recording calls.
Communication between two servers is mainly based on RFC 4240--an exception is the recording service, which is not described in this RFC.