Inbox scripting

This page documents how the relation is between the inbox of the studio and the script of the bot.

Events

When certain buttons in the inbox user interface are pushed, events are sent to the running conversation, so that the bot can do the right thing and present the correct user interface to the user.

These events are the following:

• $operator_join - when the operator joins the chat and is about to start chatting
• $operator_leave - when the operator leaves the chat, or goes offline
• $operator_action - when the operator says something
• $inbox_assign - when an operator assigns themselves to the chat.
• $inbox_unassign - when an operator unassigns themselves.
• $inbox_close - when the conversation is marked Closed in the inbox UI
• $inbox_set_role_tag - when a conversation is handed over to another team (role tag). The role tag is given in the event's payload.

Escalation to operators

To escalate a conversation from the bot to an operator you need to do a couple of things:

1. enable inbox: settings / studio settings / enable conversations inbox
2. tag "workflow:unassigned"
3. use the escalate function to escalate to all operators
4. use the wait control to force the user to wait until an operator joins

# for instance use unknown to trigger escalation
dialog __unknown__ do
    invoke escalate
end

dialog escalate do
    tag "workflow:unassigned"
    agents = escalate(message)
    if agents > 0 do
        wait_control = input_method("wait", 
            caption: "Please wait", 
            wait_time: 300,
            description: "An operator will join the chat within 5 minutes"
        )
        await wait_control, timeout: 300, timeout_value: "timeout"
    else
        say "There are currently no operators available…"
    end
end

1. add a new script called operator_joined to handle operator events. Is is not needed when you are using the DialoX basebot since it already has this file by default.

dialog event: "$operator_join", do: invoke operator_join
dialog event: "$operator_action", do: invoke operator_action

dialog operator_join do
  operator = event.payload
  say _("#{operator.first_name} has joined the chat."), class: "system", typing_indicator: 0
  tag "esc:operator_joined"
end

dialog operator_action do
  action = event.payload

  if action.type == "message" do
    say(action.payload, as: action.operator, typing_indicator: 0)
  end

  if action.type == "attachment" and action.payload.type == "image" do
    show(image(action.payload.url), as: action.operator, typing_indicator: 0)
  end
end

Advanced escalation / routing to multiple queues

If you want to escalate to different queues depending on certain logic, for instance if you have multiple departments each responsible for a different area of your business, you need to do a little bit more. Suppose you add a separate inbox for recruitment specific questions. For this we'll add for instance the role tag recruitment to the users that are equiped to answer recruitment specific questions.

1. Add role tag recruitment to your users in the admin / environment page
2. Add a corresponding inbox in settings / studio settings and give it the recruitment tag.
3. Add bubble script code to tag your conversation with the recruitment tag

tag "recruitment"

1. Add the role tag in the to: param of the escalate call

agents = escalate(message, to: "tag:recruitment")

So this would change your escalate dialog to:

dialog escalate do
    tag "workflow:unassigned"
    tag "recruitment"
    agents = escalate(message, to: "recruitment")
    if agents > 0 do
        wait_control = input_method("wait", 
            caption: "Please wait", 
            wait_time: 300,
            description: "An operator will join the chat within 5 minutes"
        )
        await wait_control, timeout: 300, timeout_value: "timeout"
    else
        say "There are currently no operators available…"
    end
end