How to Connect Botpress to WhatsApp

Select Botpress in the HITLchat setup wizard

In the left menu, click Configuration. You’ll land on the Integration Setup tab headed “Let’s get you connected!” Under Select Integration Type, choose:

• Botpress — “Connect your existing Botpress chatbot to hitlchat and get conversation handover from your bot directly to your agents.” ← select this one.
• Voiceflow — for Voiceflow 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.

Selecting Botpress on the Integration Setup screen.

Choose how to connect Botpress to WhatsApp

The next screen is headed “Choose how you’d like to connect your Chatbot”, with a WhatsApp Connection Options card. Here’s what each option means:

• WhatsApp Business API – Facebook Login (recommended) — “Instantly connect a WhatsApp Business number using your Facebook login.” HITLchat sets everything up through Meta for you.
• WhatsApp Business API – Manual Configuration — for users who already have 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.” Best for bot conversations and moderate messaging; for high-volume bulk campaigns use the official API instead to avoid number bans.

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

Connect your WhatsApp number with Facebook Login

Select WhatsApp Business API – Facebook Login. A blue Connect using Facebook Login button appears. Click it, confirm on the short info pop-up, and a Facebook window opens. Log in and either select an existing WhatsApp Business number or create one by following Meta’s prompts.

When it succeeds, you’ll see a 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

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

• Phone Number ID — in Meta, open your app → WhatsApp ▸ API Setup, pick 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. There’s an “Instructions to create an Access Token” video link right on the field.

Click Next.

Connect the Meta webhook to HITLchat

The next 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 toggle 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

Select 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 on screen.

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

Link your Botpress bot and enable human handoff

All three paths finish here. This final screen, “Botpress Hitlchat Configuration”, links HITLchat to your Botpress bot so it can route WhatsApp conversations to live agents. Fill in:

• Botpress Personal Access Token — in Botpress, click your profile (top right) → Account Settings ▸ Access Tokens ▸ Generate New Token, copy it, and paste it here.
• Botpress Messaging API URL — in Botpress Studio, click Integration Hub (top right), search for the Messaging API integration, install it, then copy the webhook URL it shows and paste it here.
• HitlChat Webhook URL — this one is read-only; copy it. Back in the Botpress Messaging API integration, paste it into the Response Endpoint URL box, click Save Configuration, and republish your bot.
• Bot Active toggle — leave on so your bot answers automatically. (You can pause the bot per-conversation later when an agent takes over.)
• Developer API Webhook (optional, WhatsApp Business API connections only) — turn this on only if you want HITLchat to also forward inbound messages and delivery statuses to your own URL.

Click Save.

Success — Botpress 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 set up any handoff keywords yet, the pop-up also nudges 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 Botpress bot replies — you’re connected. 🎉