WhatsApp Trigger

Overview

Serve a chatbot over WhatsApp (or SMS) with Twilio. The WhatsApp Trigger starts your workflow whenever someone messages your Twilio number; wire it into an AI agent and a Send WhatsApp node and you have a conversational assistant — the same agent and memory engine as the hosted chat assistant, just a different channel.

Setup has two sides: Twilio (a phone number + the webhook that points at Falcon Builder) and Falcon Builder (your Twilio credential + the flow). The walkthrough below covers both, end to end, using Twilio's free WhatsApp Sandbox so you can test without an approved business profile.

Twilio's console UI changes from time to time — if a label differs, check Twilio's official WhatsApp docs. The Falcon Builder steps below are exact.

1. Sign up for Twilio & open the WhatsApp Sandbox

• Create a Twilio account at twilio.com if you don't have one.
• In the Twilio Console, go to Messaging → Try it out → Send a WhatsApp message (WhatsApp Sandbox). The sandbox lets you send and receive WhatsApp messages immediately, without an approved business profile.
• Note the sandbox number and the join code shown there (something like join <two-words>).

2. Activate your phone for testing

• From your personal WhatsApp, send the join code (e.g. join <two-words>) to the sandbox number.
• Once Twilio confirms, any message you send to the sandbox number is relayed to your Twilio account — and on to Falcon Builder once the webhook is connected (step 5).

3. Add your Twilio credential in Falcon Builder

• In the Twilio Console dashboard, find your Account SID and Auth Token under Account Info (console.twilio.com). Use the LIVE credentials, not the test ones.
• In Falcon Builder, go to Credentials → New credential → Twilio and enter the Account SID, Auth Token, and your From number (the sandbox number while testing). See the Twilio credential guide.
• The same credential verifies inbound messages and sends replies.

4. Build the flow

1. Add three nodes and connect them in order: WhatsApp Trigger → an AI node (AI Prompt or Agent) → Send WhatsApp.
2. Attach your Twilio credential to both the WhatsApp Trigger (signature verification) and the Send WhatsApp node (sending).
3. On the AI node, set the user prompt to {{input.body}}. Enable Conversation Memory and set the Conversation ID to {{input.conversationId}} so each contact keeps their own thread.
4. On Send WhatsApp, set To to {{input.from}} and Body to the agent's response — {{agent_result.response}} (Agent) or {{ai_response.response}} (AI Prompt).

5. Connect the webhook in Twilio

1. Publish the workflow. The webhook only accepts messages while the workflow is active.
2. Open the WhatsApp Trigger's configuration panel and copy the Webhook URL.
3. Back in Twilio's WhatsApp Sandbox Settings, find the Sandbox Configuration section and paste the URL into the “When a message comes in” field.
4. Set the method to POST. Leave the status callback URL blank. Save.

6. Develop & test

Send a message to the sandbox number from your WhatsApp and confirm you get a reply from your agent. Whenever a user messages the number, Twilio posts to your webhook, your flow runs, and the Send WhatsApp node replies. If nothing comes back, re-check that the workflow is published, the credential is attached to both nodes, and the webhook URL is pasted correctly with method POST.

Inbound data available to downstream nodes

• {{input.from}} — sender's number (E.164, e.g. +61412345678)
• {{input.body}} — the message text
• {{input.profileName}} — sender's WhatsApp display name
• {{input.conversationId}} — per-contact memory key (the business number paired with the sender)
• {{input.to}}, {{input.waId}}, {{input.messageSid}}, {{input.channel}} (whatsapp or sms), {{input.numMedia}}, {{input.mediaUrls}}

The original Twilio fields are also under {{input.raw}} (e.g. {{input.raw.From}}, {{input.raw.ProfileName}}). In a Code node, use input (the trigger payload, e.g. input.from or input.raw.From) or $json (the immediately-upstream node's output) — note $input there is the n8n-style items array, not the payload.

Images & PDFs

If a user sends an image or PDF, it's passed to the AI node as vision input automatically — use a vision-capable model (e.g. GPT-4o, Claude, Gemini) and the agent can read and respond to it. Scanned/image PDFs are rendered to images so they work across every vision model. An attachment with no caption is still delivered with a neutral stand-in prompt.

Signature verification

Inbound messages are verified against your Twilio credential's auth token (the X-Twilio-Signature header), so only genuine Twilio traffic can start the workflow. Keep “Require a valid signature” on in production; turn it off only for sandbox debugging if signatures fail behind a proxy.

Move to production

Once your sandbox bot works, apply for an official WhatsApp Business profile via Twilio's WhatsApp request form. After approval, connect your business number in Twilio and update your Twilio credential's From number — users can then message you without joining the sandbox.

Always follow WhatsApp's Business Messaging Policy and your local marketing/privacy laws (e.g. Australia's Spam Act and Privacy Act). WhatsApp is strict; misuse can get a business profile banned.

The 24-hour window

• Replying within 24 hours of a user's last message is free-form — no template required. A reply bot lives entirely inside this window.
• To message a contact outside that window (proactive outreach), WhatsApp requires a pre-approved template and prior opt-in.

FAQ

My sandbox WhatsApp bot stopped responding. Twilio's sandbox connection expires after a period of inactivity. Re-send the join code (e.g. join <two-words>) to the sandbox number from your WhatsApp to reactivate it, then try again. Also confirm the workflow is still published.

Common Use Cases

• Customer support bot — answer questions over WhatsApp with an agent that has your knowledge base and remembers the conversation
• Lead qualification — greet inbound enquiries, capture details, and sync to your CRM
• Document intake — let customers send a photo of a receipt or form and have the agent read and process it
• Appointment booking — handle scheduling conversationally and confirm in the same thread

Required Credentials