Preview and Disposition Scenarios

If you implement a custom agent desktop and wish to integrate the Preview and Disposition scenarios into your Callback application, you need to configure preview and disposition options in your callback service. If you implement the Disposition scenario, you also need to create an Office Hours service.

After you do this, your custom agent application will receive the following UserEvent events from Orchestration Server:

• CallbackInvitationEvent—The callback invitation that contains the attached data for the preview. The invitation includes the list of actions that the agent can perform–accept, reject, or cancel. Your Agent application displays the actions and the attached data for the preview to the agent, then submits a Preview Response to your Callback service.
• CallbackDispositionEvent—The callback disposition event that provides the URL to which you submit the disposition selected by the agent. Your Agent application then submits a Disposition Response to your Callback service through this URL.

If the agent needs to reschedule the callback, he or she can select the retry_later disposition option provided in the disposition event. This event also provides the business_hours_url that lists the available timeslots to reschedule.

Important

Disposition scenarios do not support transfers.

Preview and Disposition Event Flow

This diagram shows the sequence of events involved in your callback service and in your Agent Desktop application if the agent receives a preview invitation and submits a disposition call after the call is done.

Steps to Handle a Preview Request

If you configure the preview feature, as detailed below, the Callback service sends a preview request to your Agent Desktop application. This request is a user event that includes the preview-specific data in the event's udata and extensions attributes. Your Agent Desktop application can use this data to:

• Show the available action(s) in the preview dialog.
• Use the provided URLs to submit their response(s) to the action(s) they select.

Configure the Preview Request Feature

To implement a preview scenario, check your settings:

1. Add an ORS Application (CME) connection to the agent's switch T-Server by using Configuration Manager or Genesys Administrator Extension (GAX).
2. In the Service Management UI, set the callback service options to the following values:
   • _agent_preview=true to enable the preview feature
   • _preview_userevent_mediatype = 0 to set the voice media (default)
   • _agent_preview_allow_reject = [0..n]
     • If _agent_preview_allow_reject=0, the reject option will not be displayed to agents.
     • Any other values indicate how many times the call can be rejected by agents, to make sure that the call cannot be rejected indefinitely.
   • _agent_preview_timeout = 30—Specify the number of seconds that the agent will be given before the preview times out. If the limit is exceeded, GMS assumes that the agent has rejected the request. (Note that the value shown here is only an example.)
   • _urs_udata_xfer_keys = "" and _attach_udata = ""–List of KVPs available within the user-data key of the CallbackInvitationEvent event.

Important

Starting in 8.5.105, the user data contains all of the KVPs attached to the real call.

In 8.5.201, additional options were added to enable new scenarios. You can now enable the rejection of previews if the agent does not accept or reject the preview invitation in the configured _agent_preview_timeout time.

If _agent_preview_timeout_set_notready=true, and if the agent does not accept or reject the preview in the configured _agent_preview_timeout:

• If the _agent_preview_set_notready_reason is not configured, the EventAgentNotReady event will be visible in the ORS logs, but will not contain a ReasonCode in its extensions.
• If the _agent_preview_set_notready_reason is configured, for example, if its value is '999', then is case, the extensions of the the EventAgentNotReady event will contain ReasonCode = '999'.

Important

Starting 8.5.201, if the agent rejects the preview invitation, this agent will not receive the preview invitation again for that callback.

Wait for the CallbackInvitationEvent

If the Preview Request Feature is configured, ORS will use the Tlib/UserEvent protocol to send a preview request invitation for Callback as a CallbackInvitationEvent UserEvent to your desktop application.

• UserEvent Name: CallbackInvitationEvent
• Limitations: The expected target is an Agent DN.

This event includes the response-options list of actions that the preview invitation dialog should display to the agent: accept, reject, or cancel (xcancel). For each action, the url property indicates the URL that the event response will be submitted to.

Example of CallbackInvitationPreview UserEvent

@12:38:49.5410 [0] 8.1.101.10 distribute_user_event: message EventUserEvent
   AttributeEventSequenceNumber   00000000000018eb
   AttributeCustomerID   'Environment'
   AttributeTimeinuSecs   541000
   AttributeTimeinSecs   1467229129 (12:38:49)
   AttributeReferenceID   2223
   AttributeUserData   [1438] 00 03 03 00..
      'display-data'(list) '1'   'v1'
                           '2'   'v2'
                           '3'   'v3'
      'response-options'(list) 'accept'(list) 'button'   'accept'
    	'url'   'http://2XX.XX.1XX.1XX:8080/genesys/1/ors//scxml/session/UGHKD84S9H6M995N2PQV7OFN3000002F/request/accept_preview'
        'reject'(list) 'button'   'reject'
        'url'   'http://2XX.XX.1XX.1XX:8080/genesys/1/ors//scxml/session/UGHKD84S9H6M995N2PQV7OFN3000002F/request/reject_preview'
       'xcancel'(list) 'button'   'xcancel'
        'url'   'http://2XX.XX.1XX.1XX:8080/genesys/1/ors//scxml/session/UGHKD84S9H6M995N2PQV7OFN3000002F/request/cancel_preview'
      'user-data'(list) 'GMS_Call_Direction'   'USERTERMINATED'
         'GMS_Cb_Desired_Time'   '2016-06-29T19:38:39.788Z'
         'GMS_Cb_Type'   'immediate'
         'GMS_Customer_Number'   '5115'
         'GMS_Orig_Service_ID'   'test123'
         'GMS_ROUTABLE'   '0'
         'GMS_RP_Used'   '8999@SIP_Switch'
         'GMS_ServiceName'   'samples_dev'
         'GMS_Service_Data_ID'   '445-748c2c27-2010-47f7-91cc-49d19a7734c3'
         'GMS_Service_ID'   '445-36922082-f275-4d44-8200-92bc5c49a965'
         'GMS_Target_Selected'   
		 '{"agent":"KSippola","dn":"7001","id":"Customer_Service",
		 "place":"SIP_Server_Place1","resource":"7001","return":"target","stat_value":"0",
		 "switch":"SIP_Switch","type":"GA","vq":"SIP_VQ_SIP_Switch"}'
        'GMS_UserTerminated_First_Connect_Party'   'AGENT'
        'GMS_VQ_Used'   'SIP_VQ_SIP_Switch'
        'RPVQID'   'I5Q83URTDD0FT2BTG0M03PT0P40000DT'
        'RTargetAgentGroup'   'Customer_Service'
        'RouterData70'   '("t"="1467229122 158")'
        'first_name'   'John'
        'last_name'   'Doe'
        'location_lat'   '37.2638324'
        'location_long'   '-122.02301459999998'
   AttributeExtensions   [118] 00 04 00 00..
      'event'   'CallbackInvitationEvent'
      'invitation-timeout'   '60'
      'session'   'UGHKD84S9H6M995N2PQV7OFN3000002F'
      'source'   'ORS'
   AttributeMediaType   '0'
   AttributeUserEvent   EventUserEvent
   AttributeThisDN   '7001'

[+] Show CallbackInvitationPreview as a JSON schema

// JSON Schema for udata passed in CallbackInvitationPreview userevent
{
    "title": "CallbackInvitationPreview Udata",
    "type": "object",
    "properties": {
        "response-options": {
            "type": "object",
            "properties": {
                "responseOption1": {
                    "type": "object",
                    "properties": {
                        "button": "accept",
                        "url": "…/request/accept_preview"
                    }
                },
                "responseOption2": {
                    "type": "object",
                    "properties": {
                        "button": "reject",
                        "url": "…/request/reject_preview"
                    }
                },
                "responseOption3": {
                    "type": "object",
                    "properties": {
                        "button": "xcancel",
                        "url": "…/request/cancel_preview"
                    }
                },
                "required": ["responseOption1", "responseOption3"]
            }

        },
        "display-data": {
            "type": "array",
            "items": {
                            "type": "string"
                    }
        },
        "user-data": {
            "type": "object",
            "properties": {
                            . . .
                    }
        }

    },
    "required": ["response-options", "display-data"]
}

// JSON Schema for extentions passed in CallbackInvitationPreview userevent
{
    "title": "CallbackInvitationPreview Extensions",
    "type": "object",
    "properties": {
        "source": {
            "enum": ["ORS"]
        },
        "event": {
            "enum": ["CallbackInvitationEvent"]
        },
        "session": {
            "type": "string"
        },
        "invitation-timeout": {
            "type": "string" // _agent_preview_timeout
        }
    },
    "required": ["source", "event", "session", "invitation-timeout"]
}

Send Preview Response

The Agent Desktop application must send the Preview Response after the agent selects one of the actions presented in the agent preview dialog.

• Description: Preview response
• Protocol: HTTP
• Method: POST
• URL: Value of the url property received in the CallbackInvitationEvent user event corresponding to the agent-selected option.
• Content-type: application/json
• Body: None
• Response from callback: HTTP 200 - Response received: (Accept|Reject|Cancel)

Reduce Processing Delays in Scheduled Preview Callback Scenario

When GMS schedules a preview callback, at a given time T, GMS sends the request to ORS at time T and ORS sends the CallbackInvitationEvent request to SIP Server at T+60 up to T+90 seconds. You can use the following options to reduce the processing delay:

• Configure _wait_for_user_confirm = false to disable the user confirmation for this service.
• Configure _max_number_of_user_availability_confirmation_attempts to limit the number of retries in your Callback service.
• Configure _user_confirm_timeout to a smaller value to reduce the waiting time for the user confirmation timeout.

Steps to Handle the Disposition Response

If you configure the Disposition feature, the Callback service will send a disposition request to the Agent Desktop application. The Agent Desktop application uses information retrieved from the user event data and the extension attributes to display the disposition dialog to the agent. It then replies with the disposition selected by the agent, as discussed in greater detail in the Disposition response section.

Important

You must create an Office Hours service before configuring the Disposition feature.

Configure the Disposition Feature

To enable the Disposition feature, configure the following settings:

1. Add an ORS Application connection to the Agent Switch T-Server Application in Configuration Manager or in Genesys Administrator Extension.
2. In the Service Management UI, set the callback service options to the following values:
   • _enable_disposition_dialog = true to enable the disposition dialog; this option is false by default to disable the feature.
   • _disposition_userevent_mediatype = 0 (voice is default)
   • _agent_disposition_timeout = 45 to set the duration in seconds for receiving an agent response. If this time elapses with no reply from the agent, GMS sets the disposition to COMPLETED with the reason NO_AGENT_DISPOSITION.
   • Set the _business_hours_service option with the name of your Office Hours service.

Wait for the Disposition Request

Once the callback is completed, if the disposition feature is enabled, GMS sends a Disposition request as a CallbackDispositionEvent UserEvent using the Tlib protocol:

• Description: Disposition request
• Protocol: Tlib/UserEvent
• UserEvent Name: CallbackDispositionEvent
• Limitations: The expected target is an Agent DN
• Body: Contains udata and extensions.

12:39:05.224 Trc 04541 RequestDistributeUserEvent received from [628] (00000004 Orchestration_Server 216.38.144.133:34716)
message RequestDistributeUserEvent
    AttributeThisDN    '7001'
    AttributeUserEvent    EventUserEvent
    AttributeCommunicationDN    '7001'
    AttributeMediaType    '0'
    AttributeExtensions    [121] 00 04 00 00..
        'disposition-timeout'    '120'
        'event'    'CallbackDispositionEvent'
        'session'    'UGHKD84S9H6M995N2PQV7OFN3000002F'
        'source'    'ORS'
    AttributeUserData    [665] 00 03 03 00..
        'config'(list) '_gms_external_base_url'    'http://216.38.144.133:8080/'
                       '_service_name'    'samples_dev'
        'display-data'(list) 'business_hours_url'    '$_gms_external_base_url$genesys/1/service/callback/$_service_name$/availability?start=$desired_time$&number-of-days=1&max-time-slots=5'
                             'completed_dispositions'    'SUCCESS,BUSY,NO_ANSWER,SIT_TONE,ANSWERING_MACHINE,CUSTOMER_NOT_KNOWN,CUSTOMER_NOT_PRESENT,WRONG_CUSTOMER_NUMBER'
                             'customer_number'    '5115'
        'response-options'(list) 'done'(list) 'button'    'done'
             'options'    '["completed","retry_now","retry_later"]'
             'url'    '$_gms_external_base_url$genesys/1/ors/scxml/session/UGHKD84S9H6M995N2PQV7OFN3000002F/request/callback_disposition'
    AttributeReferenceID    2228

In this UserEvent:

• display-data contains the information that the Agent Desktop application needs to present the agent disposition dialog.
• business_hours_url provides the list of available timeslots in case the agent selects the retry_later disposition option.
• completed_dispositions contains the list of common dispositions. The Agent Desktop can provide its own list of dispositions.
• url contains the URL to be used for submitting the disposition response.

[+] Show CallbackDispositionEvent as a JSON schema

Note that the JSON schema below is provided for the sake of clarity, as this event is always sent as a UserEvent.

// JSON Schema for udata passed in CallbackDispositionEvent UserEvent
{
    "title": "CallbackDispositionEvent Udata",
    "type": "object",
    "properties": {
        "response-options": {
            "type": "object",
            "properties": {
                "responseOption1": {
                    "type": "object",
                    "properties": {
                        "button": "done",
                        "url": "…/request/callback_disposition",
                        "options": {
                            "enum": ["completed", "retry_now", "retry_later"]
                    }
                },
                "required": ["responseOption1"]
            }
        },
        "display-data": {
            "type": "object",
            "properties": {
                "customer_number": "string",
                "business_hours_url": "/service/callback/$_service_name$/availability?start=$desired_time$&number-of-days=1&max-time-slots=5",
                "completed_dispositions": {
                    "enum": "array",
                    "properties": {
                        "button": "done",
                        "url": "…/request/callback_disposition",
                        "options": {
                            "enum": ["SUCCESS", "BUSY", "NO_ANSWER", "SIT_TONE", "ANSWERING_MACHINE", "CUSTOMER_NOT_KNOWN", "CUSTOMER_NOT_PRESENT", "WRONG_CUSTOMER_NUMBER"]
                    }
                },
                "required": ["customer_number", "business_hours_url", "completed_dispositions"]
            }
        },
        "config": { // to be used to evaluate business_hours_url specified earlier
            "type": "object",
            "properties": {
                "_gms_external_base_url": "string",
                "_service_name": "string"
            },
            "required": ["_gms_external_base_url", "_service_name"]
        }
    },
    "required": ["response-options", "display-data"]
}
// JSON Schema for extensions passed in CallbackDispositionEvent UserEvent
{
    "title": " CallbackDispositionEvent Extensions",
    "type": "object",
    "properties": {
        "source": {"enum": ["ORS"]},
        "event": {"enum": ["CallbackDispositionEvent "]},
        "session": {"type": "string"},
        "disposition-timeout": {"type": "string"}},
    "required": ["source", "event", "session", "disposition-timeout"]
}

Send a Disposition Response

The Agent Desktop application must send the Disposition Response after the agent selects one of the dispositions presented in the agent disposition dialog and before the _agent_disposition_timeout timeout occurs.

• Description: Disposition response
• Protocol: HTTP
• Method: POST
• URL: Value of the url property received in the CallbackDispositionEvent UserEvent
• Content-type: application/json
• Body:

// JSON Schema for agent response from callback disposition dialog
{
	"title": "HTTP POST body received from callback disposition dialog",
	"type": "object",
	"properties": {
		"reason" : "SUCCESS", // only for completed
		"disposition": {
			"enum": ["retry_later","retry_now", "completed"],
		},
		"customer_number": "string", // only for retry_later
		"desired_time": "string" //only for retry_later
	},
	"required": ["disposition"] // desired_time required when disposition = "retry_later"
}

Callback Response:

HTTP 200 Response received: <agent response from body of the request>

For a “completed” use case, if you choose “SUCCESS” in your agent desktop, the Disposition response contains:

• "reason" = "SUCCESS"
• "disposition" = "completed"

For a “retry_later” use case, the Disposition response contains:

• "disposition" = "retry_later"
• "customer_number" = "<customer number>"
• "desired_time" = "<timestamp>"