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

Go to Integration and select WhatsApp.

Select the WhatsApp account you want to set up.
Open the Handoff to Live Chat tab.

Turn on Enable Handoff to Live Chat. Turning this off later stops the handoff for this WhatsApp channel. Your settings are kept.
In Live Chat Channel Name, select the Live Chat channel that will receive the handed-over conversations.
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".

(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."
(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.
Click Update. You'll see the message "Your handoff to live chat settings have been saved."

Advanced settings

Setting	What it does	Default
Page hosting	Where the live chat page opens. Hosted by Qiscus: we host the page for you, no setup needed. Hosted on your website: embed the live chat on a page on your own domain.	Hosted by Qiscus
Page URL	Only for Hosted on your website. The address of the page on your website, for example `https://example.com/live-chat`.	None
Allowed domains	Only for Hosted on your website. One domain per line, starting with https://. The live chat only appears on these domains.	None
Link expires after (seconds)	Time the customer has to open the link. After that, it expires.	900
Session Duration (seconds)	How long, in seconds, the customer can keep using the same link to return to the Live Chat conversation. The time counts from when the link was sent.	86400
Messages to copy	Recent WhatsApp messages shown in the live chat, so agents have context. Set this to 0 to copy nothing.	20

If you use your own page: after you select Hosted on your website, copy the snippet from the Installation Code section into the page on your website that will receive handed-over conversations.

Hand off a conversation from the inbox

Open a WhatsApp conversation in the inbox.
Click Handoff to Live Chat in the chat header, next to Resolve.

The customer receives your invite message with the button in WhatsApp.
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".
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

Role	Can hand off
Admin	Any WhatsApp conversation
Supervisor	Any WhatsApp conversation
Agent	Only conversations they are handling

Hand off automatically with your chatbot

If a chatbot answers your WhatsApp conversations, it can send the Live Chat link at the point where it would normally hand the conversation to an agent. 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.

Send the Live Chat link

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

POST https://omnichannel.qiscus.com/api/v2/live_handover/invite

Headers

Header	Value
`Qiscus-App-Id`	Your App ID
`Qiscus-Secret-Key`	Your Secret Key
`Content-Type`	`application/json`

Body

Send room_id. All other fields are optional.

Field	Type	Default	Description
`room_id`	string	(required)	The ID of the WhatsApp room, from the webhook your bot receives.
`widget_channel_id`	integer	Channel setting	The Live Chat channel to open. Overrides the channel selected in the settings.
`ttl_seconds`	integer	Channel setting (900)	How long the customer has to tap the link for the first time. Accepts 60 to 86400.
`session_ttl_seconds`	integer	Channel setting (86400)	How long the customer can keep using the link to return to the Live Chat. Accepts 300 to 172800.
`role`	string	None	The name of one division to route the conversation to.
`roles`	array of strings	None	The names of several divisions. If you send both, `roles` is used.
`find_online_agent`	boolean	`true`	When routing by division, only assign an agent who is online.

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

Example

curl -X POST "https://omnichannel.qiscus.com/api/v2/live_handover/invite" \

-H "Qiscus-App-Id: <APP_ID>" \

-H "Qiscus-Secret-Key: <SECRET_KEY>" \

-H "Content-Type: application/json" \

-d '{

"room_id": "<WHATSAPP_ROOM_ID>",

"roles": ["Customer Service"],

"find_online_agent": true

Response

{

"action": "offered",

"jti": "<link id>",

"url": "https://.../api/v2/live_handover/c/<token>",

"widget_channel_id": 123,

"expires_at": "2026-10-01T03:15:00Z",

"session_ttl_seconds": 86400,

"sent": true,

"sent_via": "cta_url",

"wa_message_id": "wamid....",

"send_error": null

}

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_error.code`	Meaning
`window_closed`	The WhatsApp 24-hour window has closed and the channel has no fallback template.
`template_failed`	The fallback template was refused.
`rejected`	WhatsApp refused the button.
`unavailable`	WhatsApp could not be reached.

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:

Event	What it means	What your bot should do
`live_handover.session_started`	The customer tapped the link and the Live Chat room is open. The event includes `widget_room_id`.	Nothing. The conversation continues in Live Chat.
`live_handover.expired`	The customer didn't tap the link before `expires_at`.	Hand the conversation over to an agent in WhatsApp as usual, so the customer is still served.

Both events include event, app_code, room_log_id, room_id, jti, and at.

Errors

Status	Message	What to do
401	`Unauthorized`	Check your App ID and Secret Key.
402	`App is disabled`	Your app isn't active. Contact your Qiscus account team.
403	`live chat handover is not part of this app's plan`	Your plan doesn't include this feature. Contact your Qiscus account team.
400	`room_id or room_log_id is required`	Send `room_id`.
404	`room not found`	Check the room ID. The room may have been deleted.
400	`room is not a whatsapp room`	Use the ID of the WhatsApp room, not the Live Chat room.
400	`room is a group, not a customer`	Group conversations aren't supported.
400	`room is already resolved`	Use the customer's new WhatsApp room.
400	`WhatsApp channel not found`	The WhatsApp channel of this room no longer exists.
400	`live chat handover is not enabled for this WhatsApp channel`	Turn on Enable Handoff to Live Chat for the channel.
400	`widget channel not found` / `widget channel not active`	Check `widget_channel_id`, or the Live Chat channel selected in the settings.
400	`widget channel must be is_secure = true for live chat handover`	Turn on Enhance Conversation Security on the Live Chat channel.
400	`this room was already offered a link and nudged once in this session; ...`	The link has already been sent twice. Hand the conversation over to an agent in WhatsApp.
429	`too many requests`	You can send up to 5 invites per room every 60 seconds. Wait and try again.

What your customer experiences

The customer receives your invite message with the button in WhatsApp.
They tap the button. The chat opens full screen inside WhatsApp's own browser, with no login and no form to fill in.
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.
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.

Last updated on Oct 7, 2026

Was this page helpful?