How to Connect Voiceflow to WhatsApp & Enable Human Handoff (HITL)

Select Voiceflow in the HitlChat setup wizard

From the left menu, open Configuration. The Integration Setup tab loads with the heading “Let’s get you connected!” Under Select Integration Type, choose:

• Voiceflow — “Connect your existing Voiceflow chatbot to hitlchat and get conversation handover from your bot directly to your agents.” ← select this one.
• Botpress — for Botpress bots (covered in a separate guide).
• No chatbot — only if you want HitlChat for bulk WhatsApp messaging or the developer API, with no bot.

Click Next.

Choosing your integration type on the Integration Setup screen.

Choose how to connect Voiceflow to WhatsApp

Next you’ll see “Choose how you’d like to connect your Chatbot” with a WhatsApp Connection Options card. The three options are:

• WhatsApp Business API – Facebook Login (recommended) — “Instantly connect a WhatsApp Business number using your Facebook login.” HitlChat handles the Meta setup for you.
• WhatsApp Business API – Manual Configuration — for users who already hold their WhatsApp Business ID, Phone Number ID and Access Token from Meta.
• QR Code Connection — “Connect to WhatsApp by scanning a QR code using your phone. This method does not use the WhatsApp Business API.” Suited to bot conversations and moderate messaging; for high-volume bulk use the official API to avoid number bans.

The WhatsApp connection options. Pick the path below that matches your choice.

Connect your WhatsApp number with Facebook Login

Choose WhatsApp Business API – Facebook Login. A blue Connect using Facebook Login button appears — click it, confirm on the brief info pop-up, and a Facebook window opens. Sign in, then pick an existing WhatsApp Business number or create one by following Meta’s prompts.

On success you’ll see the green message “Almost done.. Click ‘Next’ to continue.” Click Next, then jump to Step 4 below.

Connect WhatsApp with manual API credentials

Enter your WhatsApp Business API credentials from Meta

Choose WhatsApp Business API – Manual Configuration and click Next. The “WhatsApp Business API Credentials (Meta)” screen asks for three values from your Meta account:

• Phone Number ID — in Meta, open your app → WhatsApp ▸ API Setup, choose your number in the From dropdown; the Phone Number ID is shown there.
• WhatsApp Business Account ID — shown on the same API Setup screen.
• Permanent Access Token — your long-lived Meta token. The field includes an “Instructions to create an Access Token” video link.

Click Next.

Connect the Meta webhook to HitlChat

The following screen, “Meta Business App Configuration”, gives you two values to paste into Meta so WhatsApp can forward messages to HitlChat:

• Meta Webhook URL — copy it. In Meta: app → WhatsApp ▸ Configuration, paste it into the Callback URL box.
• Meta Verify Token — copy it (the value is HitlChat) into the Verify token box.

Then in Meta click Verify and Save, scroll to the webhook subscriptions list, and switch the messages webhook to Subscribed.

Click Next and continue to Step 4.

Connect WhatsApp by scanning a QR code

Scan the QR code to link your WhatsApp number

Choose QR Code Connection and click Next. On the “Connect to WhatsApp using QR Code” screen, open WhatsApp on your phone → Settings ▸ Linked Devices ▸ Link a Device, and scan the code shown.

Once it shows connected, click Next and continue to Step 4.

Link your Voiceflow agent and enable human handoff

All three paths finish here. This final screen, “Voiceflow Configuration”, connects HitlChat to your Voiceflow agent so it can route WhatsApp conversations to live agents. Fill in:

• Voiceflow API Key — in Voiceflow, open your agent’s workflow, click the Settings icon on the left, then API Keys. Copy the API key and paste it here.
• Bot Active toggle — leave on so your Voiceflow agent answers automatically. (You can pause it per-conversation later when a human takes over.)
• Developer API Webhook (optional, WhatsApp Business API connections only) — enable this only if you want HitlChat to also forward inbound messages and delivery statuses to your own URL.

Click Save.

Success — Voiceflow is now connected to WhatsApp

A green “Configuration Successful” pop-up appears: “You’re ready to start sending and receiving messages! Try sending a test message to your WhatsApp number.”

If you haven’t added any handoff keywords yet, the pop-up also prompts you to Add HITL keywords — the words that transfer a chat from the bot to a human. Click Go to Inbox to start handling conversations.

Send a WhatsApp message to your number to confirm your Voiceflow agent replies — you’re connected. 🎉