If you want to enable the agent to specify which state to transition to after the live-chat session ends, use the agentActions property in the System.AgentInitiation component to list the supported actions that the agent can send, and then use the System.AgentConversation component to map the actions to states.

When the agent accepts the chat request, the chat console displays the supported actions, each of which is preceded by a slash (these are referred to as slash actions).

If the agent sends any of the slash actions, the action is sent to the live-agent transfer framework, and the skill terminates the live chat. If the System.AgentConversation has a transition for that action, the flow transitions to the named state. Note that the conclusionMessage isn't output if the agent sends a slash action.

1. Add an agentActions property to the System.AgentInitiation component, and list the supported actions.

   You can define the agentActions list elements in several ways:

   • As a list of maps, where each map must contain an action property, a label property, and optionally, a description property. For example:

           - action: "action1"
             label: "label1"
             description: "description1"
           - action: "action2" 
             label: "label2"
             description: "description2"

   • As a JSON array, where each object in the array must contain an action property, a label property, and optionally, a description property. For example:

           [
           {action: "action1",
           label: "label1",
           description: "description1"},
           {action: "action2",
           label: "label2",
           description: "description2"}      
           ]

   • As a comma-delimited string of action values. The label and description are the same as the action value. For example:

     "action1, action2"

2. (Optional) Add the agentActionsMessage property to specify a message for the live chat console to display before it lists the supported actions. For example:

     agentInitiation:
       component: "System.AgentInitiation"
       properties:
         agentChannel: "ServiceCloudIntegration"
         nlpResultVariable: "iResult"
         waitingMessage: "Let me connect you with someone who can further assist you."
         rejectedMessage: "Sorry, but no one's available now."
         resumedMessage: "Please wait, someone will be with you shortly."
         errorMessage: "Oops! We're having system issues. We're sorry, but we can't connect you with an agent right now."
         agentActionsMessage: "\nYou can terminate when done or send one of these actions.\n"
         agentActions: [{
           action: "Order",
           label: "Order",
           description: "Initiate dialog in the bot to order a pizza."},
           {action: "Cancel",
           label: "Cancel",
           description: "Initiate dialog in the bot to cancel an order."}]     
       transitions:
         actions:
           accepted: "agentConversation"
           rejected: "initiationRejected"
           error: "tryAgain"
     initiationRejected:
       component: "System.Output"
       properties:
         text: "Perhaps it's outside their working hours or it's a holiday."
       transitions:
         return: "initiationRejected"
     tryAgain:
       component: "System.Output"
       properties:
         text: "Please try again later."
       transitions:
         return: "tryAgain"

   If you don't set this property, then the default message is Here are the available actions that you can send to transfer the conversation back to the bot. Prepend the action with a forward slash (for example, /actionName).
3. Add a next transition for when the user terminates the conversation by using an exit keyword, and then add these transition actions:
   • An action for each supported action that's listed in the agentActions property in the System.AgentConversation component.
   • An agentLeft action for when the agent terminates the live chat without using a slash action or the session times out. See System.AgentConversation Transitions.
   • An expired action for when a session expires. See System.AgentConversation Transitions.
   • An error action for when the channel connection fails. See System.AgentConversation Transitions. This action only works with instances of Oracle Digital Assistant that were provisioned on Oracle Cloud Infrastructure (sometimes referred to as the Generation 2 cloud infrastructure).

     agentConversation:
       component: "System.AgentConversation"
       properties:
         agentChannel: "ServiceCloudIntegration"
         nlpResultVariable: "iResult"
         exitKeywords: "bye, exit, take care, goodbye, quit"
         expiryMessage: "Your chat with the agent timed out."
         conclusionMessage: "Your chat with the agent has ended."
         waitMessage: "You are number ${system.message.messagePayload.position} in the queue. Your waiting time is ${(system.message.messagePayload.waitTime>60)?then('${(system.message.messagePayload.waitTime/60)?int} mins','${system.message.messagePayload.waitTime} seconds')}."
       transitions:
         next: "endPrompt"
         actions:
           agentLeft: "endPrompt"
           expired: "endPrompt"
           error: "handleConversationError"
           Order: "resolvesize"
           Cancel: "cancelorder"
     endPrompt:
       component: "System.Output"
       properties:
         text: "Returning you to your bot."
       transitions:
         return: "endPrompt"

   Note
   
   The error action only works with instances of Oracle Digital Assistant that were provisioned on Oracle Cloud Infrastructure (sometimes referred to as the Generation 2 cloud infrastructure).

By default, when a chat request is submitted, the service returns a message about the queue position and wait time, which the skill outputs. For example, the message might be:

You are in position {0} in our queue. Expected wait time is {1} minute(s) {2} second(s)

"You are at number ${system.message.messagePayload.position} in the queue. Your wait time is ${system.message.messagePayload.waitTime}."

    waitMessage: "You are at number ${system.message.messagePayload.position} in the queue. Your wait time is ${(system.message.messagePayload.waitTime>60)?then('${(system.message.messagePayload.waitTime/60)?int} mins','${system.message.messagePayload.waitTime} seconds')}"

Your dialog flow needs to handle errors that might occur during agent initiation. When the System.AgentInitiation component tries to initiate a connection with the live-agent system, it might return an error or rejected action. Also, it might invoke a system error if there is a developer-caused issue.

• rejected action: This action is triggered when Oracle B2C Service rejects the connection request. Some of the reasons for rejecting a connection request are:

  • No agents are available (requires allowTransferIf and queueId properties)
  • It's outside of the configured operating hours
  • It's a holiday
  • There's a problem with the chat server

  Note that if you don't set allowTransferIf and queueId, the rejected action will not occur when no agents are available, instead, the transfer will remain in a wait condition.

  When Oracle B2C Service rejects a connection request, the skill displays a rejected message, which is Agent rejected by default. Then it transitions to the state that's mapped to the rejected action. You can use the rejectedMessage property in the System.AgentInitiation component to provide a custom message.

  Tip:

  If you have admin access to the Oracle B2C Service desktop Service Console, you can view the operating hours and holidays. From the navigation pane, click Configuration, click Site Configuration, double-click Interfaces, and then click Chat Hours.

• error action: This action is triggered when there's a problem establishing a connection with Oracle B2C Service. For example, the password in the Agent Integration channel is no longer valid, or there's a problem with the Oracle B2C Service server.

  When this type of error occurs, the skill displays the following message by default, and then transitions to the state that's mapped to the error action.

  Error transferring to agent, the reason is: <reason>, Please contact
  your system administrator to resolve this error.

  You can use the errorMessage property in the System.AgentInitiation component to override the default message.

• System errors: When the agent integration channel doesn't exist or is disabled, the skill invokes a system error. By default, the skill displays the message "Oops I'm encountering a spot of trouble. Please try again later..." Unfortunately, until a developer fixes the problem, it won't help the bot user to try again. Therefore, you might want your dialog flow to better handle these errors by adding an error transition, which goes to a state that outputs a more helpful customer-facing message. (This is different from the error action). Alternatively, you can modify the default message by going to Settings > Configuration and editing Unexpected Error Prompt. However, this change affects the skill globally.

  Note that when you validate a dialog flow, the validator will let you know if the agent integration channel is missing or disabled, so remember to do that before you test your skill or release it to the public.

  Here are some ways to diagnose a system error:

  • Click Validate in the skill to validate the dialog flow.

  • Run the skill in the Preview. When the error occurs, the error state and message (reason) are displayed in the Conversation tab.

  • In the state to which the error transition routes the flow, output a string that includes the Freemarker template ${system.errorAction}, which prints the error message (reason).

Here's an example of handling system errors and the error and rejected actions.

  agentInitiation:
    component: "System.AgentInitiation"
    properties:
      agentChannel: "B2CServiceIntegration"
      nlpResultVariable: "iResult"
      waitingMessage: "Let me connect you with someone who can further assist you."
      resumedMessage: "Someone will be with you shortly."
      errorMessage: "Oops! We're having system issues and we can't connect you with an agent right now."
      rejectedMessage: "Unfortunately, no one's available right now."     
    transitions:
      actions:
        accepted: "agentConversation"
        rejected: "initiationRejected"
        error: "tryAgain"
      error: "agentInitiationSystemError"
  initiationRejected:
    component: "System.Output"
    properties:
      text: "Perhaps it's outside their working hours or it's a holiday."
    transitions:
      return: "initiationRejected"
  tryAgain:
    component: "System.Output"
    properties:
      text: "Please try again later."
    transitions:
      return: "tryAgain"
  agentInitiationSystemError:
    component: "System.Output"
    properties:
      text: "I seem to be having a connection problem. Can you please email email@example.com to let them know?"
    transitions:
      return: "done"