Jump to: navigation, search

_ixn_redirect_hints

Section: General
Default Value:
Valid Values: JSON-formatted string
Changes Take Effect: Immediately


Sets the hints parameter of the scxml ixn:redirect request for routing the callback call to the agent. You can use this parameter to override the customer phone number presented to the agent. Use this parameter if the prefix applied to outbound numbers should not be displayed to the agent. For example, the outbound number displayed to the agent can be set as follows:

{"extensions": {"CPNDigits": "5551234"}}
Tip
This is an advanced parameter. To modify the value of an advanced parameter, you must enable Advanced Parameters in the Service Management UI.

_plugin_on_dial_associate_ixn

Section: Voice - User Terminated
Default Value: true
Valid Values: Boolean
Changes Take Effect: Immediately


True to allow the ORS session executing the custom plugin to control the call (interaction). This enables the plugin to perform some advanced actions which require the session to be in control of the interaction.

Important
Applicable only if the _plugin_on_dial_url option is set.

_plugin_on_dial_invoke_on_call_failed

Section: Voice - User Terminated
Default Value: true
Valid Values: Boolean
Changes Take Effect: Immediately


True to allow the custom plugin to be invoked even when the dialed call to the customer has failed by not being answered by a human.

Important
Applicable only if the _plugin_on_dial_url option is set.

_plugin_on_dial_associate_ixn

Section: Voice - User Terminated
Default Value: true
Valid Values: Boolean
Changes Take Effect: Immediately


True to allow the ORS session executing the custom plugin to control the call (interaction). This enables the plugin to perform some advanced actions which require the session to be in control of the interaction.

Important
Applicable only if the _plugin_on_dial_url option is set.

_plugin_on_dial_invoke_on_call_failed

Section: Voice - User Terminated
Default Value: true
Valid Values: Boolean
Changes Take Effect: Immediately


True to allow the custom plugin to be invoked even when the dialed call to the customer has failed by not being answered by a human.

Important
Applicable only if the _plugin_on_dial_url option is set.

_plugin_on_dial_url

Section: Voice - User Terminated
Default Value:
Valid Values: String
Changes Take Effect: Immediately


URL of the SCXML custom plugin to execute various custom scenarios after a user terminated callback is dialed; these scenarios depend on the state of the call. By default, there is no value for this option and the plugin execution is disabled.

_max_dial_attempts

Section: Voice - User Terminated
Default Value: 3
Valid Values: Integer
Changes Take Effect: Immediately


Maximum number of attempts to call the customer.

_treatment_call_failure_answering_machine

Section: Voice Treatment
Default Value:
Valid Values: String or as a JSON-formatted string
Changes Take Effect: Immediately


URI of the music file to play when a call is not answered by the customer and is forwarded to the answering machine. JSON-formatted strings can be used to specify hints to the RequestApplyTreatment.

The following example makes the music start playing after the answering machine beep is detected: { "file": "file_url", "hints":{ "am-beep-detection":"on"} }

By default, the value of this option is empty and Callback uses the <GMS installation>/../Resources/SampleTreatments/call_fail_ans_machine.wav file from the Callback template.

To deactivate the play treatment, set the value of this option to { }.

_treatment_customer_connect

Section: Voice Treatment
Default Value:
Valid Values: String or as a JSON-formatted string
Changes Take Effect: Immediately


URI of the music file to play when the customer answers the callback.

The JSON-formatted strings can be used to specify hints to the RequestApplyTreatment. For example:

{ "file": "file_url", "hints": {"hint1":"value"}}

_on_customer_connect_treatment_url

Section: no category
Default Value: " "
Valid Values: String URL
Changes Take Effect: Immediately


URL of a VXML application to execute after a user terminated callback is dialed and the call is answered by a human.

By default, this option is empty and the VXML execution is disabled.

_plugin_on_dial_invoke_on_call_failed

Section: Voice - User Terminated
Default Value: true
Valid Values: Boolean
Changes Take Effect: Immediately


True to allow the custom plugin to be invoked even when the dialed call to the customer has failed by not being answered by a human.

Important
Applicable only if the _plugin_on_dial_url option is set.

_plugin_on_dial_url

Section: Voice - User Terminated
Default Value:
Valid Values: String
Changes Take Effect: Immediately


URL of the SCXML custom plugin to execute various custom scenarios after a user terminated callback is dialed; these scenarios depend on the state of the call. By default, there is no value for this option and the plugin execution is disabled.

_plugin_on_dial_invoke_on_call_failed

Section: Voice - User Terminated
Default Value: true
Valid Values: Boolean
Changes Take Effect: Immediately


True to allow the custom plugin to be invoked even when the dialed call to the customer has failed by not being answered by a human.

Important
Applicable only if the _plugin_on_dial_url option is set.

_plugin_on_dial_url

Section: Voice - User Terminated
Default Value:
Valid Values: String
Changes Take Effect: Immediately


URL of the SCXML custom plugin to execute various custom scenarios after a user terminated callback is dialed; these scenarios depend on the state of the call. By default, there is no value for this option and the plugin execution is disabled.

_treatment_find_agent_fail

Section: Voice Treatment
Default Value:
Valid Values: String or JSON-formatted string
Changes Take Effect: Immediately


Music file to be played when the service fails to find the agent in the time specified by the Max Time To Wait For Agent on the Call parameter. This parameter accepts a URI as a string or as a JSON-formatted string. See also _treatment_waiting_for_agent. By default, this option has an empty value and Callback will use the <GMS installation>/Resources/SampleTreatments/all_agents_busy.wav file available in the callback template.

_treatment_call_failure_answering_machine

Section: Voice Treatment
Default Value:
Valid Values: String or as a JSON-formatted string
Changes Take Effect: Immediately


URI of the music file to play when a call is not answered by the customer and is forwarded to the answering machine. JSON-formatted strings can be used to specify hints to the RequestApplyTreatment.

The following example makes the music start playing after the answering machine beep is detected: { "file": "file_url", "hints":{ "am-beep-detection":"on"} }

By default, the value of this option is empty and Callback uses the <GMS installation>/../Resources/SampleTreatments/call_fail_ans_machine.wav file from the Callback template.

To deactivate the play treatment, set the value of this option to { }.

_treatment_customer_connect

Section: Voice Treatment
Default Value:
Valid Values: String or as a JSON-formatted string
Changes Take Effect: Immediately


URI of the music file to play when the customer answers the callback.

The JSON-formatted strings can be used to specify hints to the RequestApplyTreatment. For example:

{ "file": "file_url", "hints": {"hint1":"value"}}

_treatment_find_agent_fail

Section: Voice Treatment
Default Value:
Valid Values: String or JSON-formatted string
Changes Take Effect: Immediately


Music file to be played when the service fails to find the agent in the time specified by the Max Time To Wait For Agent on the Call parameter. This parameter accepts a URI as a string or as a JSON-formatted string. See also _treatment_waiting_for_agent. By default, this option has an empty value and Callback will use the <GMS installation>/Resources/SampleTreatments/all_agents_busy.wav file available in the callback template.

_max_time_to_wait_for_agent_on_the_call

Section: General
Default Value: 3600
Valid Values: Integer (seconds)
Changes Take Effect: Immediately


Maximum period of time (seconds) to wait for the agent to accept and answer the call after the customer is connected.

_treatment_waiting_for_agent

Section: Voice Treatment
Default Value:
Valid Values: String or JSON-formatted string
Changes Take Effect: Immediately


Music file to play when the customer is waiting for an agent. This parameter accepts a URI as a string or as a JSON-formatted string. If you do not set this option, Callback will use the default <GMS installation>/Resources/SampleTreatments/next_customer_rep.wav file of the callback template.

Play Treatments and Collect Inputs

Important
The following configuration is required for voice scenarios.

Set up Play Treatments

1

You can configure the treatments to play in the Callback and Mobile Engagement > Configured Services tab. Expand your Callback service and then, expand Voice Treatments.

  • If you are using Genesys Media Server, place the treatment files that will be used by the Callback service in the <MCP Install Dir>/GMSApplications directory and enter the name of your file.
  • For other media servers, enter the URL of your files.

In voice scenarios, the customer call can be placed in a virtual queue, waiting for an agent. You can set up custom treatments for calls waiting for an agent:

Customize Treatments for User Terminated Calls

The outbound call has Call Progress Detection (CPD) enabled. If a human answers the call, the Media Server provides the CPD result in the _call_state parameter of the request submitted to your SCXML plugin. The interaction ID is provided in the _interaction_id parameter, which is set to undefined if the call is not answered.

If you implement one of the user terminated callback scenarios, you can define treatments for outbound calls by using an SCXML plugin, a VXML application, or by setting Callback built-in treatments through your service options. Callback built-in treatments are part of the the Callback template strategy and they will be executed if you set options that start with _treatment, such as: _treatment_customer_connect, _treatment_call_failure_answering_machine, _treatment_find_agent_fail, and so on.

The figure below is a simplified diagram of the flow of the treatments. The table that follows details the Callback service options that configure the condition points in the diagram.


CLBCK-playtreatments-flow.png

Customization Answer type Options
Plugin Enabled = yes machine, human
_plugin_on_dial_url = <URL of your SCXML strategy>
_plugin_on_dial_invoke_on_call_failed= true
human only
_plugin_on_dial_url = <URL of your SCXML strategy>
_plugin_on_dial_invoke_on_call_failed= true or false
VXML Enabled = yes human only _on_customer_connect_treatment_url= <URL of your VoiceXML application>
On Connect Treatment = yes (optional) human only _treatment_customer_connect= <music file location>
Machine Treatment answering machine _treatment_call_failure_answering_machine= <music file location>
Retry Limit Exceeded = yes all Number of dial attempts > _max_dial_attempts

Implement an SCXML Plugin and Collect Inputs

1

If a user requests a new Callback Service which is CPD-enabled, Callback sends a request to the SIP Server to dial a call and waits for CPD-Results to invoke the SCXML plugin. The SCXML plugin performs the custom treatments. The plugin can also collect inputs from the caller and return an action that alters the flow of the callback. Callback waits for the plugin response, which includes the following values:

  • Mandatory: action and message.
  • Optional: customer_number, customer_number_prefix, and delay.

Then, Callback executes the action.

Important
If the customer ends the call while the plugin is executing, the plugin should detect hangup by the customer and return the response with its action set to cancel or retry, and its message set to interaction_deleted. Otherwise, the plugin message value should always be set to OK.

Invoke your Plugin

Callback invokes the SCXML plugin by starting an SCXML session with the full path to an SCXML entry page provided in the _plugin_on_dial_url option, for example:

_plugin_on_dial_url = http://server:port/StrategyName/src-gen/IPD_Pluging_Entry.scxml


The Callback strategy generates the Callback parameters listed in the table below, and adds them to the <session:start> request, in the request-specific attribute of the request's body:

Parameter name Parameter description
_call_state JSON-formatted call state object returned by ORS on a successful CPD. Set to a value from the _genesys.ixn.callState documented enumeration.

Possible values are:

  • Ok=0 (human answer)
  • NoAnswer=7
  • SilDetected=8
  • AnsweringMachineDetected=9
  • FaxDetected=17

_interaction_id Set to the interactionID, or undefined for the no answer case.
_customer_number Customer number dialed prior to the plugin invocation.
_gms_service_id GMS Service ID responsible for this Callback.
_ors_service_id ORS Service ID responsible for this Callback.
_user_data User data passed to the user request when starting Callback.
_dial_attempt Number of outbound attempts made to connect to the customer (includes the current attempt).
_ttl Time To Live (in seconds) that Callback waits to receive a response. Callback must receive the response before TTL expires to continue the processing of the Callback service request; otherwise, the Callback session will exit with an error. The TTL value is set by the _plugin_on_dial_timeout option of your Callback service in the Admin UI.
_reply_url HTTP URL to which the plugin must send the asynchronous response after the execution of the plugin logic.

The plugin strategy needs to use these parameters for various purposes. You can get examples of how you can use them in the code of the Custom Callback Plugin Sample.

Invoke Plugin For No Answer or Machine Answer

By default, the _plugin_on_dial_invoke_on_call_failed option of your Callback service is true and invokes the plugin if the outbound call is not answered or is answered by machine. To disable the plugin invoke in that scenario, configure _plugin_on_dial_invoke_on_call_failed=false.


In a no answer scenario:

  • The _interaction_id parameter is set to undefined.
  • The _call_state parameter is set to NoAnswer (7).
Important
In this scenario, the plugin should return a reply message with its action parameter set to cancel or retry.

In a machine answer scenario:

  • The _call_state parameter is set to AnsweringMachineDetected (9).
  • If the SIP Server configuration has the TServer / am-detected option set to connect, the call remains connected and _interaction_id is set to the corresponding voice interaction ID. In that case, the plugin can play a message to be recorded.
  • Otherwise, SIP Server hangs up the call and _interaction_id is set to undefined.

Invoke Plugin with Attached Call

By defaut, the _plugin_on_dial_associate_ixn option is set to true in your Callback service's configuration and passes the control of the voice interaction (call) to the plugin.

  • Before returning the reply, the plugin must detach the call to allow Callback to regain control of the interaction. See the Custom Callback Plugin Sample example for further details. The Plugin sample includes a re-usable sub-workflow that performs the detach interaction step and returns the plugin response.
  • The plugin must monitor the interaction.deleted event; if this event occurs, the plugin must return a reply with its message parameter set to interaction_deleted and its action parameter set to either cancel or retry.

Disabling the plugin's interaction control (by setting _plugin_on_dial_associate_ixn=false) provides compatibility with the earlier release of the plugin feature.

Important
Genesys recommends to pass the interaction's control to the SCXML plugin to ensure the best compatibility with Composer strategies. Composer's various interaction-related blocks are configured by default to handle the interaction.added and interaction.present events that occur when the interaction is associated to the plugin session.

Invoke Plugin with no Attached Call

Composer strategies are built to start processing when an interaction is attached to the Orchestration session, but the plugin is invoked with no attached interaction if you set the following options in your Callback service configuration:

If there is no attached call, the Callback session sends an event named plugin.start to the plugin session and you must force the strategy to start by adding the following event to the interaction process diagram of the strategy. Refer to the Custom Callback Plugin for an example of the Composer plugin strategy that includes this event handling in the interaction process diagram.

Name = plugin start
Event = plugin.start
Body:
<log expr="'plugin.start in IPD event handler. Starting application with no interaction'"/>
 <assign location="system.SessionID" expr="_sessionid"/>
 <assign location="system.StartEvent" expr="_event"/>
 <assign location="App_StartEvent" expr="_event"/>
 <raise event="application.start">
 	<param name="interactionid" expr="undefined"/>
 </raise>

Actions and Inputs Returned in the Plugin Response

By sending a request to the existing session (<session:fetch>), the plugin returns an asynchronous response to the Callback URL received in the _reply_url parameter of the query. The response is included in parameters named action and message. For example:

<session:fetch requestid="requestId"  srcexpr="_data._reply_url"
	    	   method="'post'" timeout="30">
	  	<param name="action" expr="replyAction"/>
	  	<param name="message" expr="replyMesg"/>
</session:fetch>
Action returned Type of answer Callback behavior
cancel all Callback cancels the request.
route_to_agent human or machine Callback routes the call to an agent. If an agent is not immediately available, the music file configured by the _treatment_waiting_for_agent parameter is played.
route_to_rp human or machine Callback routes the customer call to the destination specified by the message parameter. The destination can be any valid value for the destination of a Composer "Force Route" block, for example an ACD Queue, Destination Label, or Routing Point.

The router priority and age of the call are respectively set in the GMS_URS_PRIORITY and RouterData70 attached data keys.

  • You can retrieve and use the GMS_URS_PRIORITY value to set the interaction priority if the interaction is added to another queue.
  • The RouterData70 value will automatically be used by URS to set the interaction age if the interaction is added to another queue.
retry all Callback dials out again unless the maximum number of retry attempts has been reached, in which case the request is cancelled.

The plugin can optionally return a customer number, a customer number prefix, or a retry time delay in seconds. If included, these values override the service configuration values.

If the callback service has the _ixn_redirect_hints parameter set to {"extensions": {"CPNDigits": "5557777"}}, the value of the CPNDigits key is updated in the returned customer_number value. See the Callback Service Options Reference for additional details.

The following example includes the optional parameters:

<session:fetch requestid="requestId" srcexpr="_data._reply_url"
method="'post'" timeout="30">
<param name="action" expr="'retry'"/>
<param name="message" expr="'Ok'"/>
<param name="delay" expr="300"/>
<param name="customer_number" expr="'555-2336'"/>
<param name="customer_number_prefix" expr="91"/>
</session:fetch>

Invoke a VXML Interface

The sequence for executing a VXML application is the same as that for the plugin detailed above, except that the VXML application is only invoked for human answers. The built-in treatment path is taken for the other cases.

The requirements for the VXML response are identical to the plugin case, but the response must be returned in an exit namelist object named treatment_result. For example:

<var name="treatment_result" expr="{'action':'route_to_agent', 'message': 'Ok'}"/><exit namelist="treatment_result"/>

Feedback

Comment on this article:

blog comments powered by Disqus
This page was last modified on May 23, 2018, at 00:09.