Handoff to Live Chat

What is Handoff to Live Chat?

Handoff to Live Chat moves a WhatsApp conversation into a Live Chat room when a human agent needs to take over. The customer taps a button in WhatsApp, and the chat opens right away inside WhatsApp's own browser. They don't need to install an app, log in, or fill in a form.

Replies sent in the Live Chat room are not charged per message by WhatsApp. This saves the most on long conversations that need many replies.

For your team, the customer is the same person on both channels:

• The latest messages from the WhatsApp conversation are copied into the Live Chat room, so the agent can see what has already been discussed.

• If an agent is already handling the WhatsApp conversation, the Live Chat room is assigned to that same agent.

• Both rooms appear in the same Omnichannel inbox.

When to use it

Handoff to Live Chat fits you best if:

• Your service conversations often take many replies, such as consultation, after-sales troubleshooting, bookings, or document checks.

• WhatsApp is your main published service channel, and your customers mostly use their phones.

• Human agents reply to customers in these conversations.

Before you start

• Your plan must include Handoff to Live Chat. If it doesn't, the Handoff to Live Chat tab appears greyed out with the message "This feature isn't included in your current plan".

• Only an Admin can change the settings. Admins, Supervisors, and Agents can use the handoff button in the inbox (see Who can hand off a conversation).

• You need a connected WhatsApp channel.

• You need a Live Chat channel with Enhance Conversation Security turned on. You can't save the handoff settings with a Live Chat channel that has this option turned off (see security in Live Chat).

  • We recommend creating a separate Live Chat channel for handoff instead of reusing the widget channel on your public website.

  • If an agent is already handling the WhatsApp conversation, the Live Chat room goes to that same agent. Otherwise, it is assigned based on the agents and allocation settings of the Live Chat channel, so make sure that channel has agents assigned before you go live.

Set up Handoff to Live Chat

1. Go to Integration and select WhatsApp.

2. Select the WhatsApp account you want to set up.

3. Open the Handoff to Live Chat tab.

4. Turn on Enable Handoff to Live Chat. Turning this off later stops the handoff for this WhatsApp channel. Your settings are kept.

5. In Live Chat Channel Name, select the Live Chat channel that will receive the handed-over conversations.

6. Under Invite Message, write the WhatsApp message that is sent to the customer together with the button:

   1. Message Text (required): up to 1,024 characters. Example: "Our team is ready to help. Continue the conversation using the button below."

   2. Button Text (required): up to 20 characters. Example: "Continue in Live Chat".

7. (Optional) Turn on Send a greeting message and fill in Greeting Text.

   1. This message is sent once, right after the customer arrives in Live Chat, so they don't see an empty chat while they wait for an agent. Example: "Hi! You're now chatting with our team here. An agent will reply shortly."

8. (Optional) Open Advanced settings to choose where the live chat page is hosted, which domains can display it, and how long links and sessions stay active.

9. Click Update. You'll see the message "Your handoff to live chat settings have been saved."

Keep the link active after resolve

By default, the live chat link stops working as soon as an agent resolves the Live Chat conversation. Turn on Keep link active after resolve if you want customers to be able to reopen the same link after that, until the session ends.

1. In the Handoff to Live Chat tab, find the Keep link active after resolve card.

2. Turn on the switch. The setting is saved right away, with no Update button.

3. Check how long the link stays active. The card shows the current session length, for example "Customers can reopen the link until the session ends: 24 hours after they first open it."

4. (Optional) To change it, click Change session duration. This takes you to Session duration (seconds) in Advanced settings. Enter a new value, then click Update in that section.

How the setting works:

• It applies per WhatsApp channel and is off by default.

• It only keeps links the customer has already opened. A link that was never opened still stops working when the conversation is resolved.

• The link still ends early if the customer ends the chat from the live chat page, or if an agent ends the session.

• Turning the setting off doesn't end links that are already active. They keep working until their session ends, the customer ends the chat, or an agent ends the session.

Advanced settings

Hand off a conversation from the inbox

1. Open a WhatsApp conversation in the inbox.

2. Click Handoff to Live Chat in the chat header, next to Resolve.

3. The customer receives your invite message with the button in WhatsApp.

4. When the customer taps the button and sends their first message, a new Live Chat room appears in the inbox:

   1. The latest WhatsApp messages are shown at the top of the room.

   2. If you were handling the WhatsApp conversation, the Live Chat room is assigned to you.

   3. The WhatsApp room shows the system message "Continued in Live Chat", and the Live Chat room shows "Continued from WhatsApp".

5. Reply in the Live Chat room the same way you reply to any Live Chat conversation.

The Handoff to Live Chat button only appears when:

• the conversation is a one-to-one WhatsApp conversation (not a group),

• the conversation isn't resolved, and

• Enable Handoff to Live Chat is turned on for that WhatsApp channel.

Who can hand off a conversation

Hand off automatically with your chatbot

If a chatbot answers your WhatsApp conversations, it can send the Live Chat link in two situations:

• Hand the customer to an agent. The bot sends the link at the point where it would normally hand the conversation to an agent. An agent is assigned in the Live Chat room. This is the default.

• Move the conversation and keep the bot. The bot sends the link so the conversation continues in Live Chat, and the bot keeps answering the customer there. No agent is assigned until the bot hands over to one.

The bot picks one of these each time it sends a link, with the handler field. The steps below are for the developer who maintains your chatbot.

Before you start

• Handoff to Live Chat is included in your plan.

• Enable Handoff to Live Chat is turned on for the WhatsApp channel (see Set up Handoff to Live Chat).

• The selected Live Chat channel is active and has Enhance Conversation Security turned on.

• The conversation is a one-to-one WhatsApp conversation, not a group.

• You have your App ID and Secret Key.

If you want the bot to keep serving the Live Chat room (handler: "bot"), also check that:

• The chatbot integration is turned on and has a webhook URL. The bot receives the customer's Live Chat messages at this URL.

• Automatic agent allocation is turned off for your app, and so is a custom agent allocation webhook. If either one is on, an agent would be assigned as soon as the customer writes in Live Chat, so the link is always sent as an agent link.

• Your bot can reply in a Live Chat room and can hand a Live Chat conversation over to an agent or a division, the same way it does in other channels.

Send the Live Chat link

When the bot decides the customer needs a human, call this endpoint:

Headers

Body

Send room_id. All other fields are optional.

The division fields (role, roles, find_online_agent) only apply when the link is an agent link and no agent is handling the customer in WhatsApp. Otherwise, the Live Chat room goes to the agent who is already handling the conversation.

When handler: "bot" is changed to agent

The link is sent as an agent link, even if the bot asked for bot, when:

• An agent is already handling the customer in WhatsApp. That agent keeps the customer.

• The chatbot integration is turned off or has no webhook URL.

• Automatic agent allocation or a custom agent allocation webhook is turned on for your app.

• A Live Chat session from this WhatsApp conversation is already running. A new link reopens the same session, so it keeps the handler that session started with (this can also be bot).

Links sent with the Handoff to Live Chat button in the inbox are always agent links.

The response always shows the final value in handler, so your bot can tell when its request was changed.

Example: move the conversation and keep the bot

Example: hand the customer to an agent

Response

• handler is who will serve the Live Chat room: bot or agent. It is saved in the link when the link is created. Sending another invite later doesn't change a link that was already sent.

• action is offered for the first link. If the bot calls again while that link is still valid, the customer gets a reminder and action is reinvited. A third call in the same session returns an error.

• sent_via is cta_url when the link goes out as a button inside the WhatsApp 24-hour window. It is template when the window has closed and the channel's fallback template is sent instead.

• If the message can't be sent, the call still returns 200 and a valid url. The response then has sent: false and a send_error:

Send the link with your own message

By default, Qiscus sends the link to the customer as a WhatsApp message with one button. You can change that message's text, footer, and button label in the channel settings. If that is enough for you, you don't need this option.

Send "send": false when your bot needs to send the link in its own message, for example a message with more than one button, or a link inside a longer bot reply.

The response still contains the link in url. Qiscus doesn't send anything to the customer, and the response has sent: false, sent_via: null, and send_error: null. Use the link as the URL of a button in your own message.

When you send the link yourself:

• Outside the WhatsApp 24-hour window, use an approved template. WhatsApp refuses custom interactive messages once the window has closed.

• Send the link from your latest call. Each new call cancels the previous link if the customer hasn't tapped it yet.

• Every call counts toward the two-per-session limit, even when nothing is sent. Call the endpoint only when you are going to send the link.

• The link still expires. If the customer doesn't tap it before expires_at, your bot receives live_handover.expired.

What happens in the Live Chat room

In bot mode, when the customer needs a person, the bot hands the Live Chat room over to an agent or a division the same way it does in any other room. From then on the room works like a normal handover.

If the customer opens the link again while the Live Chat room is still open, they go back to the same room. Whoever is serving it (the bot or an agent) stays the same.

Handle the result in your bot

Qiscus sends one of these events to your bot's webhook URL, in the same format as other bot messages. Both events now include handler, so your bot knows which case it is in.

Both events include event, app_code, room_log_id, room_id, jti, handler, and at. session_started also includes widget_room_id.

The value of handler in these events is the one the link was created with. It can be different from what your bot sent in the invite (see When handler: "bot" is changed to agent above).

Errors

What your customer experiences

1. The customer receives your invite message with the button in WhatsApp.

2. They tap the button. The chat opens full screen inside WhatsApp's own browser, with no login and no form to fill in.

3. If they close the page, they can tap the same button again to go back to the same conversation, until the link's time limit ends (24 hours by default) or the conversation is resolved.

4. If the link has expired or been used up, the page says the link is no longer valid and asks the customer to reply in WhatsApp to get a new one.

Important notes

• The invite message is billed like any other WhatsApp message. Replies sent after that in Live Chat are not charged per message by WhatsApp.

• The invite message can only be sent while the WhatsApp 24-hour window is open.

• You can send the link at most twice per session. If the customer comes back to WhatsApp, you can click Handoff to Live Chat again.

• Resolving the Live Chat room ends the Live Chat session. Resolving the WhatsApp room doesn't end it.

• Follow-ups at a later time, such as the next day, still need a WhatsApp message.

FAQ

Q: If the customer closes the Live Chat page and opens the link again, is the earlier conversation lost? A: No. As long as the link's time limit (24 hours by default) hasn't ended and the conversation hasn't been resolved, the customer goes back to the same conversation. The chat history from that session is still there

Q: Is the WhatsApp conversation history brought over to Live Chat? A: Yes. The latest WhatsApp messages (20 by default) are copied into the Live Chat room, so the agent has the context.

Q: If Agent A was handling the conversation in WhatsApp, will Agent A also handle it in Live Chat? A: Yes. The Live Chat room is assigned automatically to the agent who was handling the WhatsApp conversation. If no one was handling it, the Live Chat channel's normal agent allocation applies.

Q: Why does the link expire? A: For security. Anyone with the link can open the customer's conversation. If a link were leaked or forwarded, it could be used to pose as the customer, or to learn the conversation's contents. A time limit reduces that risk. Your Admin can change the limit in Advanced Settings, but a longer limit makes the link less secure.

Q: Does the customer need to fill in their name or phone number? A: No. The customer's identity is carried over from WhatsApp, so your agent can see who the customer is.