By the Flowra team. The labels below come from the Flowra dashboard and the Flowra docs. Screenshots marked "website preview" come from the interactive demo on the channels page, not from a live account. We checked the escalation and takeover settings in the dashboard but have not run the takeover flow end to end on a live WhatsApp number, so if a label or behavior on your account differs, follow what you see. This guide uses Flowra's WhatsApp QR toolkit (a linked WhatsApp account via QR), not Meta's WhatsApp Business Cloud API. Checked 26 Sep 2026.

What you'll build

The flow looks like this:

1. A customer writes to your linked WhatsApp number.
2. The Flowra agent searches your FAQ and replies in the same WhatsApp chat.
3. If the agent decides the message fits one of your escalation rules, such as "customer asks for a human", it sends your handoff message and stops auto-replying in that chat.
4. You open the conversation under External Users, choose Take over, and reply. Your messages go out on WhatsApp from the linked number.
5. When you're done, you choose Hand back and the agent answers new messages again.

You don't have to wait for an escalation, either. You can take over any WhatsApp conversation whenever you want to step in.

Handoff is about who is talking to the customer. If you'd rather have the agent ask you before it runs a risky tool, such as a refund, that is a separate Flowra feature, and the Telegram guide covers it: human approval for sensitive actions. For deciding which steps need a person in real time and which only need a later review, see human in the loop vs human on the loop.

What you need

• A WhatsApp account you are allowed to link for support (phone with WhatsApp installed). Prefer a dedicated number for business support, not your personal day-to-day chat account.
• A Flowra account on Premium ($19.99/mo) or Pro ($49.99/mo). WhatsApp QR accounts are not included on Free (Instagram Business is also excluded from Free). On paid plans that include it, a connected WhatsApp QR account bills 50 credits per day, and the tools for this app are included with no extra per-call charge. See pricing.
• Your support content: FAQ, shipping and returns policy, as files, URLs or pasted text.
• Optional: a Slack or email account, if you want the agent to alert you when it hands a chat over.

WhatsApp QR vs WhatsApp Business API. This tutorial is only about Flowra's WhatsApp QR toolkit: send and receive messages (and manage groups, contacts, and profile) on a linked WhatsApp account. It is not Meta's WhatsApp Business Cloud API. Browse the catalog at toolkits and look for WhatsApp QR.

Step 1: Link WhatsApp with WhatsApp QR

Unlike Telegram (where you create a bot with BotFather), WhatsApp QR links an existing WhatsApp account to Flowra with a QR code — similar in spirit to WhatsApp Web / Linked Devices.

1. In Flowra, check the project and End user switchers in the sidebar. Connections belong to the selected end user. Default user is fine for a solo setup; keep everything in this tutorial under the same one.
2. Start the WhatsApp QR connect flow. The Connection page only lists accounts you've already linked; its empty state points you to connect "from a workflow agent, MCP server, or tool run flow". The simplest path is the agent's WhatsApp entry point (step 3): under Connected account, choose Select or connect account, then Connect New Account.
3. Flowra first shows Daily credits for WhatsApp QR (50 credits per connected account per day, with the app's tools included). Choose Continue to get the QR code.
4. On your phone, open WhatsApp → Linked Devices (or the equivalent on your OS) and scan the QR code shown in Flowra.
5. Return to Connection and confirm the row shows Active. Other statuses you might see are Failed, Expired and Initializing.

Some toolkits show a daily credit seat while connected. Pricing lists WhatsApp QR at 50 credits per connected account per day until you disconnect, and the connect dialog shows that rate before you continue.

Dedicated account tip. Linking gives Flowra's agent tools the ability to send and receive on that account. Do not link a personal number you also use for family and friends unless you accept that risk. Prefer a number reserved for support.

Step 2: Create the agent and write its instructions

In Flowra, open Workflows & Agents in the sidebar and choose Create Agent (or Create by AI to have a chat helper draft it for you to review and save).

Keep the same project and End user as in step 1. Agents, connections and knowledge belong to the selected end user.

Fill in Identity / Intelligence (names follow the UI tabs):

• Basic Info: a Name (for example "WhatsApp Support"), an optional Description, and optional Starter prompts.
• Agent Intelligence: the System Instructions, a model, and Temperature. A lower temperature suits support answers that should stick to your policy.

Here is an example set of system instructions. Adapt it to your business; it is a starting point, not a Flowra default.

EXAMPLE — adapt before use.

You are the support assistant for Acme Store on WhatsApp.

Scope
- Answer questions about orders, shipping, returns and product care.
- Answer only from the attached knowledge collection.
  If the answer is not there, say you don't know and offer to pass the chat to a teammate.

Style
- Short, friendly, plain language. Two to four sentences unless the customer asks for detail.
- Reply in the customer's language.

Orders and refunds
- To look up an order, ask for the order number. Never ask for passwords,
  full card numbers or one-time codes.
- Never promise a refund, discount, replacement or delivery date.
  Explain the policy, and pass refund requests to a teammate.

Escalation
- If the customer asks for a person, wants a refund, is angry,
  or mentions legal action, hand the chat to a teammate.

WhatsApp
- Stay in this chat. Do not ask the customer to move to email unless they prefer it.
- Never ask them to share screenshots of bank cards, OTPs or full ID documents in chat.

Instructions shape what the agent tries to do. The escalation settings in step 4 are what actually stop it from replying when a chat needs you.

Step 3: Attach WhatsApp as a messaging entry point

You already connected the WhatsApp QR account in step 1. Now attach it to the agent so inbound messages wake it.

1. Open the agent and find the Entry points tab (Channels).
2. Choose Add entry point, pick Messaging channel, then select WhatsApp in the channel list.
3. In the Configure panel, under Connected account, choose Select or connect account and pick your WhatsApp QR account (or Connect New Account if you haven't linked one yet). The trigger filters below (regex, sender JIDs, message type, groups) are optional. Then choose Connect channel.
4. Save the agent and check that its Active switch is on.

Replies go out through the linked WhatsApp account. The docs flag one warning, repeated in the UI: anyone who can message that channel can wake the agent. A public WhatsApp number is a public entry point, so keep the tool list small (step 5) and set up escalation (step 4).

Each person who messages the number becomes an external user (source Channel), with their chats kept separate.

Step 4: Set up escalation

Escalation tells the agent which situations need a person. Open the agent's Behavior tab and find the Escalation card.

1. Turn on Enable escalation. When it's off, the rest of the card is ignored.
2. Under Escalate when…, add the situations that should reach you. You can type your own, for example "customer asks for a human", or pick from the card's suggestions: "refund request", "legal or compliance question", "customer is angry or threatening", "payment dispute" and "account deletion request". The agent decides when a message fits one of these, so describe each situation clearly.
3. Under What to do when escalating, pick one of the two options that pause the agent on WhatsApp:
   • Reply only (pauses channel chat): the agent sends your handoff message, then stops auto-replying in that chat until you answer from External Users or hand the chat back.
   • Notify tool (pauses channel chat): the same pause, plus an alert to you through a notification tool, such as Slack or email. First attach that tool on the agent's Actions tab, then pick it in the card's Notify tool picker.
4. Write the Handoff message, for example "Thanks for your patience. A teammate from Acme Store will reply here shortly." As far as we could see, this is the only notice the customer gets when the chat changes hands, so make it clear.

The card has a note worth reading before you test. On messaging channels such as WhatsApp, Reply only and Notify tool are enforced: the agent has to hand the chat over, and auto-reply stays paused. In the dashboard chat and the embedded website widget, escalation only works through the prompt, so a test there won't pause anything.

Step 5: Add knowledge and (optionally) tools

Knowledge. Open Knowledge and use Chat with Knowledge to add your FAQ and policies as files, URLs or text; there is no separate ingest form. Then tick the collection on the agent's Data access card, and search tools for it are added automatically when the agent runs.

Tools. On the Tools card, open Select Tools and use the Toolkits tab. For a store, that might be Shopify for order lookups, or Slack if you want to pick it as the notification tool in step 4. Connect the matching account under Your accounts for testing or on the Connection page. Browse available apps on the toolkits catalog.

Two rules keep this safe:

• Attach as few tools as possible. The docs recommend a small tool set, and the product may warn when too many are pinned.
• Keep money moves with people. With handoff in place, refunds and order changes can go to you instead of the agent. If you do attach a tool that moves money, put it behind Flowra's separate approval setting, as shown in the Telegram guide.

Leave Let visitors use my accounts off unless you deliberately want channel visitors to run selected apps with your connection.

Step 6: Take over a chat and hand it back

When a chat needs you, whether the agent escalated it or you simply want to step in:

1. Open External Users in the dashboard. Each WhatsApp customer appears there as an external user.
2. On the customer's row, choose Chat to open their conversation. If they have written on more than one channel, pick the WhatsApp thread.
3. The header shows an Agent badge while the agent is in charge, and the reply box says "Take over to reply on this channel". Choose Take over.
4. The badge changes to You and the reply box says "Reply to the person on this channel…". Type your reply and send it. It goes out on WhatsApp from the linked number, and the agent stays quiet in this chat.
5. When you're done, choose Hand back. The badge returns to Agent and the agent answers new messages again.

A few things to know before you rely on it:

• The customer may not be told that a person joined. As far as we could see, they get your handoff message after an escalation and then your replies, with no other notice. If you take over manually without an escalation, no handoff message is sent at all, and they only see your replies. Introduce yourself in your first message, for example "Hi, this is Sam from the team."
• Takeover works on channel conversations only. It covers WhatsApp and the other messaging channels. Conversations from the website chat widget don't have Take over controls.
• Check what the agent knows after hand-back. We couldn't confirm whether the agent reads your own messages as context when it takes the chat back. Before you hand back, make sure the customer's question is closed, or say in your last message what happens next.

Step 7: Test the whole flow

1. Test answers in the dashboard. Open Chat, select the agent, and ask a few FAQ questions. Remember that escalation doesn't pause the agent here.
2. Test on WhatsApp. From another phone (or a second WhatsApp account), message the linked number with a routine question. You should get a reply in the same chat.
3. Trigger the handoff. From the same phone, write "Can I talk to a person?". You should get your handoff message, and further messages shouldn't get an automatic reply.
4. Take over and hand back. Open the conversation under External Users, choose Take over, send a reply, and check it arrives on the test phone. Then choose Hand back, send another routine question from the phone, and check that the agent answers.
5. Check the logs. Tool execution logs show each tool's input and output, and Full statistics on the agent shows runs, credits and errors.

Before going live: if the agent kept replying after "Can I talk to a person?", stop there. Check that escalation is enabled, that your Escalate when… entries clearly describe the situation, and that you picked Reply only or Notify tool. Then test again on WhatsApp, not in the dashboard chat.

Security notes for a linked WhatsApp account

WhatsApp QR is more like linking WhatsApp Web than creating a Telegram bot token. Treat the link as high trust:

• Session risk. While the account stays connected, agent tools can send and receive on that number. Disconnect under Connection if you stop using the agent, if you see unexpected sends, or if the phone is lost.
• Who can wake the agent. Anyone who can message the number can start a run. Keep send-blast, group-admin and money-moving tools off an agent that anyone can message.
• PII in chat. WhatsApp customers often paste order numbers, addresses and IDs. Keep grounding on your knowledge base, refuse to collect passwords/OTPs/full card numbers in instructions, and use usage caps under Behavior.
• Dedicated number. If the same account is also your personal WhatsApp, the agent shares that inbox surface. Prefer a support-only number.
• Not the official API. The QR connection links a regular WhatsApp account the way WhatsApp Web does. It does not go through Meta's official WhatsApp Business Cloud API, and WhatsApp may restrict or ban numbers that send automated messages. Keep this setup to answering customers who write to you, and use the WhatsApp Business Cloud API for high-volume messaging.
• Plan and seat cost. WhatsApp QR needs Premium or Pro, and each connected account draws 50 credits per day while linked. Disconnect idle accounts.

Troubleshooting and limits

• The agent doesn't reply on WhatsApp. Check that the WhatsApp QR connection is Active (reconnect / re-scan if it shows Expired or Failed), that the WhatsApp messaging entry point is attached, and that the agent's Active switch is on. Also check whether the chat is still taken over or paused after an escalation; if it is, hand it back.
• The agent keeps replying after a customer asks for a person. See the "Before going live" check in step 7.
• There's no Take over button. Takeover only exists on channel threads. A website widget or dashboard chat conversation won't show it.
• QR won't scan or link fails. Refresh the connect flow, check phone network, and try again from Linked Devices. Confirm your plan includes WhatsApp QR (Free does not).
• Things "disappear". Check the project and end user switchers.
• Plan limits. Free cannot connect WhatsApp QR. On paid plans you may still hit Plan limit reached after your agents/workflows cap.
• Credits. Model tokens, catalog tool runs (5 credits each), runtime beyond the first minute, and the WhatsApp QR daily seat (50 credits/day) all draw from one balance. Watch Full statistics during your first week.

When to use n8n, Zapier or Make instead

With n8n, Zapier or Make you'd usually build handoff yourself: store a "human mode" flag for each conversation, check it before the bot replies, and send your own replies through the same WhatsApp integration. That gives you full control, and n8n also lets you self-host, but it's logic you maintain in every workflow. Flowra vs n8n covers the difference in more detail.

Choose Flowra when the agent is the product: one agent on WhatsApp (and later Telegram, Slack or your site), each customer kept separate, and escalation plus Take over and Hand back built into the dashboard.

FAQ

Where do I take over a WhatsApp conversation?

In the Flowra dashboard. Open External Users, choose Chat on the customer's row to open their conversation, and choose Take over. Choose Hand back when you're done.

Does the customer know a person took over?

As far as we could see, only through your handoff message (sent after an escalation) and your own replies. A manual takeover without an escalation sends no handoff message, so introduce yourself in your first message.

Do I have to wait for the agent to escalate before I take over?

No. You can take over any channel conversation manually, whether or not escalation is turned on.

Can I take over chats from the website chat widget?

No. Takeover applies to channel conversations such as WhatsApp. In the website widget and the dashboard chat, escalation only works through the prompt, and there are no Take over controls.

How do I find out that a chat needs me?

Attach a notification tool such as Slack or email on the agent's Actions tab, set What to do when escalating to Notify tool (pauses channel chat), and pick that tool in the Notify tool picker. You're then alerted when the agent hands a chat over. With Reply only, check External Users.

Can I build this on the Free plan?

No. WhatsApp QR accounts are not included on Free. You need Premium or Pro, which include WhatsApp QR accounts. A connected account also uses 50 credits per day. See pricing.

Is this Meta's WhatsApp Business Cloud API?

No. This guide uses Flowra's WhatsApp QR toolkit: a WhatsApp account linked via QR. Meta's WhatsApp Business Cloud API is a separate product. Look for WhatsApp QR in the toolkits catalog.

Can WhatsApp restrict or ban my number for this?

It can. The QR connection links a regular WhatsApp account and does not go through Meta's official WhatsApp Business Cloud API, and WhatsApp may restrict or ban numbers that send automated messages. Use a dedicated number, keep the agent to answering customers who message you, and use the WhatsApp Business Cloud API for high-volume messaging.

What if the linked session is compromised or I see unexpected messages?

Disconnect WhatsApp QR under Connection immediately, review Executions and tool logs, and re-link only when you are ready. Prefer a dedicated support number.

Can the same agent answer on Telegram or my website later?

Yes. Add more messaging entry points (Telegram, Slack, Discord, Gmail), or create a website widget for the same agent. You don't need to copy the agent for each channel. The Telegram walkthrough is here: Telegram support agent with approval.

Next steps

Browse the other messengers on the channels page, or clone a support agent from the templates. When you're ready, choose a plan that includes WhatsApp QR and link your account.