Asterisk Genesys SIP Server Integration

Image

How-To integrate Asterisk with Genesys SIP Server


1. Architecture

1.1 Overview

Image

Figure 1 - Architecture overview

  • Endpoints are registered on Asterisk only. They are not registered on SIP Server.
  • Agent desktop is required in order to maintain agent status (logged in, logged out, ready, not ready) toward SIP Server.
  • Agent desktop is also required in order for the agent to control (hold, transfer, conference, ... ) SIP Server calls.
  • Stream Manager is optional. Most of the Stream Manager capabilities (music on hold, conference, and treatments) can be reproduced in Asterisk.

1.2 Private calls vs. Contact Center calls

The concept of the integration with Asterisk PBX relies on 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.

This principle removes the need for SIP Server to be engaged in the signaling of each and every call.

1.2.1 Private calls

Asterisk dial plan can be setup in such a way that private calls (direct calls to agent for example) are not forwarded to SIP Server. Instead only the notification about the busy status of the endpoint is going to be passed to SIP Server. SIP Server uses this status change notification to set the endpoint DN in a busy state (EventAgentNotReady) so that the rest of the Genesys suite will not consider that DN available for routing of the contact center calls. The principle of private call is represented in the following picture.

Image

Figure 2 - Schematic for a private call


1.2.2 Contact center calls

The same way Asterisk dial plan is setup to bypass SIP Server for private calls, some rules can be written such as contact center calls (calls to the service number of the company typically) are connected by Asterisk to SIP Server. From that point SIP Server triggers a strategy in order for 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 toward Asterisk for the selected endpoint. Asterisk finally delivers the call the agent endpoint.

This mechanism creates a signaling "loop" inside SIP Server who is then in charge of maintaining the inbound leg from Asterisk (customer leg) with the outbound leg to Asterisk (agent leg).

Note: From Asterisk standpoint, those 2 legs are seen as 2 completely separate calls. Correlation is performed at SIP Server level

By staying in the signaling path, SIP Server is aware of any call status change and can therefore produce call related events (EventRinging, EventEstablished, EventReleased, ...). Any call control operation from the agent has to be performed using third party call control (3pcc) procedure. In other words, agent desktop *must* be used for any call control operation (beside the answer call operation). This includes but is not limited to hold, transfer and conference requests. The principle of contact center call is represented in the following picture.

Image

Figure 3 - Schematic for a contact center call


2 Call Flows

2.1 Subscription

At startup, SIP Server sends subscription messages in order to be notified about the endpoints status change. Asterisk PBX provides NOTIFY messages to SIP Server according to the endpoints status.If the endpoints are not registered yet, Asterisk PBX reports their status as ‘closed’.

As soon as an endpoint register toward Asterisk, a NOTIFY message is sent to SIP Server with status reported as ‘open’.

2.2 Private Call

For private calls, the Asterisk dialing plan is made such as the call is directed directly toward the endpoint. Asterisk notifies SIP Server about the call activity on that particular endpoint. In this case, SIP Server generates EventAgentNotReady so that overall agent status is seen as non available for contact center calls.

Image

Figure 4 - A private inbound call


As soon as the call is released from the endpoint, Asterisk notifies SIP Server which then generates EventAgentReady so that the agent is now considered as available for contact center calls.
Note: The exact same mechanism happens for private outbound calls. SIP Server just sees NOTIFY message provided by Asterisk.

2.3 Contact Center Call

2.3.1 Inbound call

Inbound contact center calls are programmed within Asterisk dial plan to be directed toward SIP Server. In this case the call hits a routing point and URS is triggered. For example, a call treatment can be requested (RequestApplyTreatment) and SIP Server terminates the dialog to Stream Manager.

Image

Figure 5 - Handling a contact center call


Whenever the agent becomes ready, SIP Server receives a RequestRouteCall message to the targeted agent endpoint. Such endpoint is configured to point to Asterisk PBX, so SIP Server is then initiating a new dialog toward Asterisk. Asterisk forwards the call to the specified endpoint and reports to SIP Server about call activity on that endpoint with a NOTIFY message (EventAgentNotReady). Eventually the call is answered, Stream Manager is disconnected and original SIP dialog is renegotiated between SIP Sever and Asterisk.

Because SIP Server is in the signaling path for the contact center calls, all call related events (EventRinging, EventEstablished, ...) are also generated.

Image

Figure 6 - Delivering the call to the agent


Then when the call is released, Asterisk notifies SIP Server with a NOTIFY message just like for the case of private calls (EventAgentReady). And because SIP Server is in the signaling path for that call, EventReleased is also generated.

Image

Figure 7 - Contact center call disconnection


2.3.2 Outbound call

Outbound that is contact center related (calling back a customer for example) must be performed using 3pcc operations. This is to ensure that SIP Server creates and controls the SIP dialogs on behalf the agent endpoint.

The make call procedure in that case is the one described by RFC3727 (flow 1).

Agent initiates the outbound call with RequestMakeCall request. SIP Server sends INVITE to agent endpoint (via Asterisk).

Note: If the phone is not configured with auto answer, then the agent needs to manually answer the call. This is the only manual action that is required for contact center calls.


Then SIP Server makes usage of Stream Manager resource in order to produce a ringback tone to the agent.

Image

Figure 8 - Engaging the agent endpoint for outbound call


Then SIP Server contacts the requested destination number. For external numbers, a rule shall be configured within SIP Server to dial out via Asterisk again (see External access via Asterisk paragraph).

Once the destination answers the call, SIP Server disconnects ringback tone (BYE to Stream Manager) and renegotiates with the agent endpoint (via Asterisk) so that media stream is connected between the agent and the customer.

Image

Figure 9 - Connecting to the customer


Although disconnection would work if it were initiated directly from the agent endpoint, it is good practice to always use desktop application in order to perform any contact center call related action.

Therefore the disconnection is requested with RequestReleaseCall to SIP Server. SIP Server managing the 2 dialogs toward the agent and the customer is sending BYE message to both of them and the call is eventually disconnected.

Image

Figure 10 - Outbound call disconnection


3 Configuration

3.1 Environment

This chapter describes the following environment.
  • Asterisk is connected to the network via a SIP gateway
  • 2 SIP endpoints 2001 and 2002 are registered toward Asterisk
  • Each endpoint is associated with a TLib desktop application

Image

Figure 11 - Environment used for description


3.2 Genesys configuration

3.2.1 SIP Server application

There are no particular configuration options related to Asterisk integration at SIP Server application level.

3.2.2 Asterisk Trunk DN in the SIP Server Switch configuration

The presence SUBSCRIBE/NOTIFY channel is configured by a DN of type ‘Trunk’ within SIP Server Switch configuration object. The name choice for that DN is arbitrary.

Options needed for this ‘Trunk’ DN are summarized in the following table.
Option (TServer section) Value Description
contact <sip uri> Indicates the host and SIP port where SIP Server shall send SUBSCRIBE message. This is the Asterisk contact in that case.
subscribe-presence-domain <string> Domain name that is passed in SUBSCRIBE request uri.
subscribe-presence-from <sip uri> Full uri that is passed into From header of SUBSCRIBE message.
subscribe-presence-expire <integer> Value of the SUBSCRIBE ‘Expires’ header.


For example:

Image

Figure 12 - Asterisk Trunk DN


3.2.3 Asterisk Extensions

For each Asterisk endpoint that needs to be monitored/controlled by SIP Server, a corresponding DN of type ‘Extension’ shall be created.

Options needed for the ‘Extension’ DN are summarized in the following table.
Option (TServer section) Value Description
contact <sip uri> Indicates the host and SIP port where SIP Server shall send INVITE message to the endpoint. This is the Asterisk contact in that case.
dual-dialog-enabled false Consultation calls are handled using the same SIP dialog toward Asterisk.
make-call-rfc3725-flow 1 3pcc make call flow to be used according to RFC3725.
refer-enabled false When using RFC3725 flow, REFER usage toward Asterisk shall be disabled.
reuse-sdp-on-reinvite true Never send a re-INVITE without SDP to Asterisk.
sip-hold-rfc3264 true RTP stream hold is done using RFC3264 method (‘sendonly’).
subscribe-presence <string> This is the name of the ‘Trunk’ DN that is configured for presence subscription messages toward Asterisk.


For example:

Image

Figure 13 - Asterisk Extension DN


3.2.4 External access via Asterisk

In order for SIP Server to contact external numbers by going through Asterisk, one or several ‘Trunk’ DN can be configured with contact option set to Asterisk address and port. For example, the following ‘Trunk’ DN defines a rule where any number starting with digit ‘0’ (and not recognized by SIP Server as an internal DN) shall be directed to Asterisk.

Image

Figure 14 - A rule to dial out via Asterisk


Multiple rules can be defined. This part of the configuration is identical to the case where SIP Server is deployed in standalone mode. Accesses to gateways are replaced in this case by access to Asterisk.

3.3 Asterisk configuration

The following section describes configuration on the Asterisk side.
This is just an example of a possible Asterisk configuration and there may be plenty of other ways to configure Asterisk.

3.3.1 sip.conf

Two peers are configured describing both the gateway and SIP Server access. For example:

[gwsim]
type=peer
host=10.0.0.1
port=5066
context=default
canreinvite=no

[gsip]
type=peer
username=gsip
host=10.0.0.1
context=default
canreinvite=no


Then each endpoint needs to be declared too. The user name of the endpoint shall match the ‘Extension’ DN configured on SIP Server side.
For example:


[2001]
type=friend
username=2001
host=dynamic
context=default
notifyringing=yes
canreinvite=no

[2002]
type=friend
username=2002
host=dynamic
context=default
notifyringing=yes
canreinvite=no


Note: SIP Server does not support receiving authentication challenges. For this reason, Asterisk users must not be configured with secret option. If user were configured with such option, Asterisk would challenge INVITE messages issued by SIP Server on behalf the user and SIP Server would not respond to the challenge.


3.3.2 extensions.conf

On the dial plan side, each endpoint monitored by SIP Server shall contain a ‘hint’ entry. This is in order for Asterisk to properly accept presence subscription (from SIP Server in that case) for those endpoints.

exten => 2001,hint,SIP/2001
exten => 2001,1,Dial(SIP/2001,60)
exten => 2002,hint,SIP/2002
exten => 2002,1,Dial(SIP/2002,60)


A very basic dial plan is configured for contact center calls.


; Inbound call to routing point 2400 -> contact SIP Server
exten => 2400,1,Dial(SIP/${EXTEN}@gsip)


Equally basic is the dial plan for calls to external numbers.

; Any number with prefix ‘0’ -> contact gateway (with remaining digits only)
exten => _0.,1,Dial(SIP/${EXTEN:1}@gwsim,60)



Image

How-To integrate Asterisk with Genesys SIP Server


1. Architecture

1.1 Overview

Image

Figure 1 - Architecture overview

  • Endpoints are registered on Asterisk only. They are not registered on SIP Server.
  • Agent desktop is required in order to maintain agent status (logged in, logged out, ready, not ready) toward SIP Server.
  • Agent desktop is also required in order for the agent to control (hold, transfer, conference, ... ) SIP Server calls.
  • Stream Manager is optional. Most of the Stream Manager capabilities (music on hold, conference, and treatments) can be reproduced in Asterisk.

1.2 Private calls vs. Contact Center calls

The concept of the integration with Asterisk PBX relies on 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.

This principle removes the need for SIP Server to be engaged in the signaling of each and every call.

1.2.1 Private calls

Asterisk dial plan can be setup in such a way that private calls (direct calls to agent for example) are not forwarded to SIP Server. Instead only the notification about the busy status of the endpoint is going to be passed to SIP Server. SIP Server uses this status change notification to set the endpoint DN in a busy state (EventAgentNotReady) so that the rest of the Genesys suite will not consider that DN available for routing of the contact center calls. The principle of private call is represented in the following picture.

Image

Figure 2 - Schematic for a private call


1.2.2 Contact center calls

The same way Asterisk dial plan is setup to bypass SIP Server for private calls, some rules can be written such as contact center calls (calls to the service number of the company typically) are connected by Asterisk to SIP Server. From that point SIP Server triggers a strategy in order for 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 toward Asterisk for the selected endpoint. Asterisk finally delivers the call the agent endpoint.

This mechanism creates a signaling "loop" inside SIP Server who is then in charge of maintaining the inbound leg from Asterisk (customer leg) with the outbound leg to Asterisk (agent leg).

Note: From Asterisk standpoint, those 2 legs are seen as 2 completely separate calls. Correlation is performed at SIP Server level

By staying in the signaling path, SIP Server is aware of any call status change and can therefore produce call related events (EventRinging, EventEstablished, EventReleased, ...). Any call control operation from the agent has to be performed using third party call control (3pcc) procedure. In other words, agent desktop *must* be used for any call control operation (beside the answer call operation). This includes but is not limited to hold, transfer and conference requests. The principle of contact center call is represented in the following picture.

Image

Figure 3 - Schematic for a contact center call


2 Call Flows

2.1 Subscription

At startup, SIP Server sends subscription messages in order to be notified about the endpoints status change. Asterisk PBX provides NOTIFY messages to SIP Server according to the endpoints status.If the endpoints are not registered yet, Asterisk PBX reports their status as ‘closed’.

As soon as an endpoint register toward Asterisk, a NOTIFY message is sent to SIP Server with status reported as ‘open’.

2.2 Private Call

For private calls, the Asterisk dialing plan is made such as the call is directed directly toward the endpoint. Asterisk notifies SIP Server about the call activity on that particular endpoint. In this case, SIP Server generates EventAgentNotReady so that overall agent status is seen as non available for contact center calls.

Image

Figure 4 - A private inbound call


As soon as the call is released from the endpoint, Asterisk notifies SIP Server which then generates EventAgentReady so that the agent is now considered as available for contact center calls.
Note: The exact same mechanism happens for private outbound calls. SIP Server just sees NOTIFY message provided by Asterisk.

2.3 Contact Center Call

2.3.1 Inbound call

Inbound contact center calls are programmed within Asterisk dial plan to be directed toward SIP Server. In this case the call hits a routing point and URS is triggered. For example, a call treatment can be requested (RequestApplyTreatment) and SIP Server terminates the dialog to Stream Manager.

Image

Figure 5 - Handling a contact center call


Whenever the agent becomes ready, SIP Server receives a RequestRouteCall message to the targeted agent endpoint. Such endpoint is configured to point to Asterisk PBX, so SIP Server is then initiating a new dialog toward Asterisk. Asterisk forwards the call to the specified endpoint and reports to SIP Server about call activity on that endpoint with a NOTIFY message (EventAgentNotReady). Eventually the call is answered, Stream Manager is disconnected and original SIP dialog is renegotiated between SIP Sever and Asterisk.

Because SIP Server is in the signaling path for the contact center calls, all call related events (EventRinging, EventEstablished, ...) are also generated.

Image

Figure 6 - Delivering the call to the agent


Then when the call is released, Asterisk notifies SIP Server with a NOTIFY message just like for the case of private calls (EventAgentReady). And because SIP Server is in the signaling path for that call, EventReleased is also generated.

Image

Figure 7 - Contact center call disconnection


2.3.2 Outbound call

Outbound that is contact center related (calling back a customer for example) must be performed using 3pcc operations. This is to ensure that SIP Server creates and controls the SIP dialogs on behalf the agent endpoint.

The make call procedure in that case is the one described by RFC3727 (flow 1).

Agent initiates the outbound call with RequestMakeCall request. SIP Server sends INVITE to agent endpoint (via Asterisk).

Note: If the phone is not configured with auto answer, then the agent needs to manually answer the call. This is the only manual action that is required for contact center calls.


Then SIP Server makes usage of Stream Manager resource in order to produce a ringback tone to the agent.

Image

Figure 8 - Engaging the agent endpoint for outbound call


Then SIP Server contacts the requested destination number. For external numbers, a rule shall be configured within SIP Server to dial out via Asterisk again (see External access via Asterisk paragraph).

Once the destination answers the call, SIP Server disconnects ringback tone (BYE to Stream Manager) and renegotiates with the agent endpoint (via Asterisk) so that media stream is connected between the agent and the customer.

Image

Figure 9 - Connecting to the customer


Although disconnection would work if it were initiated directly from the agent endpoint, it is good practice to always use desktop application in order to perform any contact center call related action.

Therefore the disconnection is requested with RequestReleaseCall to SIP Server. SIP Server managing the 2 dialogs toward the agent and the customer is sending BYE message to both of them and the call is eventually disconnected.

Image

Figure 10 - Outbound call disconnection


3 Configuration

3.1 Environment

This chapter describes the following environment.
  • Asterisk is connected to the network via a SIP gateway
  • 2 SIP endpoints 2001 and 2002 are registered toward Asterisk
  • Each endpoint is associated with a TLib desktop application

Image

Figure 11 - Environment used for description


3.2 Genesys configuration

3.2.1 SIP Server application

There are no particular configuration options related to Asterisk integration at SIP Server application level.

3.2.2 Asterisk Trunk DN in the SIP Server Switch configuration

The presence SUBSCRIBE/NOTIFY channel is configured by a DN of type ‘Trunk’ within SIP Server Switch configuration object. The name choice for that DN is arbitrary.

Options needed for this ‘Trunk’ DN are summarized in the following table.
Option (TServer section) Value Description
contact <sip uri> Indicates the host and SIP port where SIP Server shall send SUBSCRIBE message. This is the Asterisk contact in that case.
subscribe-presence-domain <string> Domain name that is passed in SUBSCRIBE request uri.
subscribe-presence-from <sip uri> Full uri that is passed into From header of SUBSCRIBE message.
subscribe-presence-expire <integer> Value of the SUBSCRIBE ‘Expires’ header.


For example:

Image

Figure 12 - Asterisk Trunk DN


3.2.3 Asterisk Extensions

For each Asterisk endpoint that needs to be monitored/controlled by SIP Server, a corresponding DN of type ‘Extension’ shall be created.

Options needed for the ‘Extension’ DN are summarized in the following table.
Option (TServer section) Value Description
contact <sip uri> Indicates the host and SIP port where SIP Server shall send INVITE message to the endpoint. This is the Asterisk contact in that case.
dual-dialog-enabled false Consultation calls are handled using the same SIP dialog toward Asterisk.
make-call-rfc3725-flow 1 3pcc make call flow to be used according to RFC3725.
refer-enabled false When using RFC3725 flow, REFER usage toward Asterisk shall be disabled.
reuse-sdp-on-reinvite true Never send a re-INVITE without SDP to Asterisk.
sip-hold-rfc3264 true RTP stream hold is done using RFC3264 method (‘sendonly’).
subscribe-presence <string> This is the name of the ‘Trunk’ DN that is configured for presence subscription messages toward Asterisk.


For example:

Image

Figure 13 - Asterisk Extension DN


3.2.4 External access via Asterisk

In order for SIP Server to contact external numbers by going through Asterisk, one or several ‘Trunk’ DN can be configured with contact option set to Asterisk address and port. For example, the following ‘Trunk’ DN defines a rule where any number starting with digit ‘0’ (and not recognized by SIP Server as an internal DN) shall be directed to Asterisk.

Image

Figure 14 - A rule to dial out via Asterisk


Multiple rules can be defined. This part of the configuration is identical to the case where SIP Server is deployed in standalone mode. Accesses to gateways are replaced in this case by access to Asterisk.

3.3 Asterisk configuration

The following section describes configuration on the Asterisk side.
This is just an example of a possible Asterisk configuration and there may be plenty of other ways to configure Asterisk.

3.3.1 sip.conf

Two peers are configured describing both the gateway and SIP Server access. For example:

[gwsim]
type=peer
host=10.0.0.1
port=5066
context=default
canreinvite=no

[gsip]
type=peer
username=gsip
host=10.0.0.1
context=default
canreinvite=no


Then each endpoint needs to be declared too. The user name of the endpoint shall match the ‘Extension’ DN configured on SIP Server side.
For example:


[2001]
type=friend
username=2001
host=dynamic
context=default
notifyringing=yes
canreinvite=no

[2002]
type=friend
username=2002
host=dynamic
context=default
notifyringing=yes
canreinvite=no


Note: SIP Server does not support receiving authentication challenges. For this reason, Asterisk users must not be configured with secret option. If user were configured with such option, Asterisk would challenge INVITE messages issued by SIP Server on behalf the user and SIP Server would not respond to the challenge.


3.3.2 extensions.conf

On the dial plan side, each endpoint monitored by SIP Server shall contain a ‘hint’ entry. This is in order for Asterisk to properly accept presence subscription (from SIP Server in that case) for those endpoints.

exten => 2001,hint,SIP/2001
exten => 2001,1,Dial(SIP/2001,60)
exten => 2002,hint,SIP/2002
exten => 2002,1,Dial(SIP/2002,60)


A very basic dial plan is configured for contact center calls.


; Inbound call to routing point 2400 -> contact SIP Server
exten => 2400,1,Dial(SIP/${EXTEN}@gsip)


Equally basic is the dial plan for calls to external numbers.

; Any number with prefix ‘0’ -> contact gateway (with remaining digits only)
exten => _0.,1,Dial(SIP/${EXTEN:1}@gwsim,60)



Created by: slavas, Last modification: Sun 03 of Jun, 2007 (02:38 UTC)
Please update this page with new information, just login and click on the "Edit" or "Discussion" tab. Get a free login here: Register Thanks! - Find us on Google+