Human Agent Transfer Implementation

Transferring a mobile end-user from an intelligent chat Flow to a live human agent and back.

Introduction

During an automated, intelligent flow-driven conversation, it may be necessary or desired to bring in a live, human agent for the user to chat with. There are many reasons to bring a live human agent into the conversation, such as:

  • The user asks for a live person
  • The endpoint of the conversational Flow is an 'Assisted Sale'
  • The user is having trouble finding the answer to their question

Example

A user contacts your company's WhatsApp number and seeks information about returning a product.
From the menu, the user selects FAQs and then asks how to make a return. Either the answer doesn't exist in the FAQ, or the user does not understand the answer and asks to speak with someone. At this point, the Flow notifies a human agent via Front that a user requires assistance. The Flow is 'paused' while the agent chats with the user and explains the return process. Once the user's question has been satisfactorily answered, the agent asks the user to take a satisfaction survey and, upon approval, hands the user back to the Flow for a CSAT survey.

User Flow

  • User asks to speak with a person
  • The Flow passes the request to Front
  • A live agent picks up the request and chats with the user on WhatsApp
  • Once the user's issue is resolved, the live agent passes the user back to the automated Flow

Requirements

Front

  • An Active Front instance
  • An Active bot in your Front instance
  • A Front API Token specifically for the Flow

Yalo Studio

  • Human FrontApp Activity Template added to your Flow
  • Webhook URL for Front

Implementing the Human-Agent Transfer Activity

Building this activity is straightforward but requires code modification, and there are several pieces of information to collect beforehand.

Before you start

Collect the following information from your instance of Front:

  • Bot Agent - the email address assigned to Front for this kind of activity
  • Bot Tag - this is a typical 'bot,' but please confirm that there is no other tag that should be used
  • Front App API Authorization Token - permits the Flow to send messages to Front via their API
  • Message - the message to be sent to Front. Typically this is something like "User is waiting for an agent" and should indicate that a user is requesting a live person
  • source - for WhatsApp, this is always 'custom'

🚧

Front is Managed By Yalo

If your Front instance is provided and managed by Yalo, you will need to file a support ticket to get the above information and to have an API authorization token generated.

Step One: Add the Human Frontapp activity to your Flow

  1. Click the New Activity button
  2. Find the Human Frontapp activity in the Activity Gallery and select it
  3. Click 'Add to Workflow'
The Flow Builder Activity Template Gallery displays a grid of available activity templates for your Flow.The Flow Builder Activity Template Gallery displays a grid of available activity templates for your Flow.

The Flow Builder Activity Template Gallery displays a grid of available activity templates for your Flow.

Step Two: Configure the activity to work with your instance of Front App

  1. Open the new activity by selecting it in the Activities sidebar
  2. Select the Human Start step and expand the code view, it will look something like this:
-- Connect to Front App
-- Config object sent to Front App with API request
body = {
    bot = {
        nextState = {
            script = {
                options = {
                    botAgent = "ADD EMAIL ADDRESS HERE", -- email address configured for Front Inbox
                    botTag = "bot", -- bot tag, this is usually the default
                    frontAppToken = "ADD FRONTAPP TOKEN HERE", -- an auth token is needed to connect to FrontApp
                    humanTag = "help", -- tag for the user request type
                    message = "User is waiting for an agent.", -- message to be sent to FrontApp
                    source = "custom", -- custom is the default for WhatsApp, this should not need to be changed
                    userId = Context.get("userId"), -- the user's WhatsApp number
                }
            }
        }
    }
}

body = JSON.encode(body) --encodes body as a JSON

result = Invoke.cloudFunction("frontapp-scripts-human-mode", body) -- call to the lambda script that handles the connection to Front App

botAgent and frontAppToken are the critical variables here.

  • botAgent is the email address associated with your Front inbox
  • frontAppToken is the Front App API authorization token
    Once you have updated the Code Action, close the code window and save your work

The second activity step, Human Session, does not require any configuration

The third step, Back from Front App, does not require any configuration. However, we do need the webhook URL it provides to configure Front to hand the conversation back to the Flow after the live agent session ends. Make sure to copy this URL.

Custom Webhook URL from Flow Builder for Front App integrationCustom Webhook URL from Flow Builder for Front App integration

Custom Webhook URL from Flow Builder for Front App integration

The final activity step, Human End also does not require changes but you may want to update the message copy or button options to be more tailored to your Flow.

At this point, it is a good idea to make sure that all steps in your Flow are saved. After Front is configured in the next step, you will be able to test the activity to ensure it works properly.

Step Three: Configure Front to Send the User Back to the Flow

🚧

If Front Is Managed by Yalo

If your Front instance is provided and managed by Yalo, you will need to file a support ticket to get the following rule created.

The last requirement we have is to configure Front for returning the user to the Flow chat in WhatsApp. This step requires that we create a rule in Front that determines when the live agent portion of the conversation is over and what to do at that point (send the user back to the Flow).

Rules in Front are fairly simple, we define a WHEN clause, an IF clause, and a THEN clause.

  • WHEN determines when the rule should be evaluated
  • IF determines whether the rule evaluates to true
  • THEN defines what happens when the rule is true

For this activity we would define the following in our Rule:

  • Run the rule when an outbound (to the user) message is sent
  • If the conversation is in the correct inbox and the message starts with a specific text for a goodbye message
  • Then do the following:
    • Send to a webhook (the webhook URL from our Flow)
    • Remove tag 'help'
    • Add tag 'bot'
    • Unassign (this unassigns the conversation from the agent)

Here's what that might look like in Front

Front App Rule Conditions for Human Agent ActivityFront App Rule Conditions for Human Agent Activity

Front App Rule Conditions for Human Agent Activity

Front App Rule Actions for Human-Agent ActivityFront App Rule Actions for Human-Agent Activity

Front App Rule Actions for Human-Agent Activity

Considerations

This guide describes only how to configure the Human Frontapp activity. You will need to decide how users will engage with this activity. Is it through a specific menu option? Is it at the end of a failed FAQ? Should they be able to speak to an agent whenever they ask for one?


What’s Next
Did this page help you?