n8n with the official WhatsApp Business API: integration guide

Updated on October 25, 2026

To connect n8n to the official WhatsApp Business API, you have two options: use the native WhatsApp Business Cloud node (to send) and WhatsApp Trigger node (to receive), connected directly to a Meta app, or use the generic Webhook and HTTP Request nodes, which work with the Cloud API and with any provider that forwards Meta’s webhooks. The native nodes are faster to set up; the generic route gives you more control and avoids the one-webhook-per-app limitation.

This guide explains what each node does, which credentials they need, the mistakes that most often block the integration, and a sample workflow that receives messages and replies automatically.

n8n nodes for WhatsApp

According to the n8n documentation, the WhatsApp Business Cloud node supports these operations:

Resource	Operations
Message	Send, Send and Wait for Response, Send Template
Media	Upload, Download, Delete

The WhatsApp Trigger starts a workflow from account events. The trigger page lists: Messages, Message Template Status Update, Message Template Quality Update, Template Category Update, Phone Number Quality Update, Phone Number Name Update, Account Update, Account Review Update, Business Capability Update and Security.

Two operations stand out:

• Send and Wait for Response pauses the workflow until the person approves, rejects or fills in a form. It’s useful for human approval, including before an AI agent runs a tool.
• Unsupported operations (marking as read, sending interactive lists, managing templates) can be done with the HTTP Request node using the same WhatsApp credential, through the Predefined Credential Type option.

Credentials: what n8n asks for

n8n uses two credential types, according to the WhatsApp credentials page:

Node	Type	Fields
WhatsApp Business Cloud	API key	Access Token and Business Account ID (the WABA ID)
WhatsApp Trigger	OAuth2	Client ID (App ID) and Client Secret (App Secret)

On Meta’s side you need a developer account, a business portfolio, a business-type app with the WhatsApp product, privacy policy and terms URLs filled in, and the app in Live mode.

One important caveat: the token generated under WhatsApp > API Setup in Meta’s dashboard is temporary. If you paste it into the credential, the workflow stops sending once it expires. For production, generate a permanent system user token and use it in the Access Token field.

Option 1: native nodes (WhatsApp Trigger + WhatsApp Business Cloud)

Step by step for an auto-reply workflow:

1. Create the OAuth2 credential with your app’s App ID and App Secret.
2. Add the WhatsApp Trigger and select the Messages event.
3. Add an IF node so the flow only continues when there’s a message (the Messages event also carries delivery statuses).
4. Add the WhatsApp Business Cloud node with Message > Send, the API key credential, the Sender Phone Number and the recipient taken from the trigger.
5. Publish the workflow.

The three WhatsApp Trigger pitfalls

The n8n docs describe limitations that explain most “nothing arrives” cases:

• One webhook per app. Meta only allows one webhook URL per app. If the same app already sends events to your CRM, n8n will replace that URL.
• Test vs. production. Switching between the test and production URLs overwrites the registered URL. Testing a published workflow can cut off production traffic. The suggested workaround is to unpublish while testing and publish again afterwards.
• WABA subscription. Publishing the workflow registers the URL but does not subscribe the app to the WhatsApp Business Account (WABA). Without that subscription, messages never arrive and no failed execution shows up. A successful test from Meta’s dashboard does not confirm the subscription.

To check and fix the subscription:

# List apps subscribed to the WABA (use the WABA ID, not the phone_number_id)
curl "https://graph.facebook.com/v26.0/WABA_ID/subscribed_apps" \
  -H "Authorization: Bearer $TOKEN"

# Subscribe the token's app to the WABA
curl -X POST "https://graph.facebook.com/v26.0/WABA_ID/subscribed_apps" \
  -H "Authorization: Bearer $TOKEN"

The token needs the whatsapp_business_management permission. Don’t send a DELETE to subscribed_apps to fix a webhook error: it stops all events for the WABA. If the WABA or the number has an override_callback_uri, events go to that other URL instead, so check it when messages go missing.

Option 2: Webhook + HTTP Request

The Webhook node accepts any POST, and HTTP Request calls any API. With them, n8n becomes just another consumer of Meta’s webhook, in the standard entry[].changes[].value format. This route makes sense when:

• the app’s webhook is already used by another system, or you use a provider that delivers events to several URLs;
• you need operations the native node doesn’t offer;
• you want to validate signatures, deduplicate events or return 200 before processing.

Webhook node settings that matter:

Setting	Recommended value	Why
HTTP Method	POST	Events arrive via POST
Respond	Immediately	Returns 200 right away and prevents retries from the source while the workflow runs
Authentication	Header Auth, when the source supports it	Stops anyone else from triggering the workflow
IP(s) Allowlist	Optional	Restricts who can call the URL

The Webhook node’s default max payload is 16 MB (adjustable on self-hosted instances with N8N_PAYLOAD_SIZE_MAX), above the 3 MB Meta indicates for webhook payloads.

If you integrate directly with Meta, the URL must also answer the GET verification: add a second Webhook node on the same path with the GET method and reply through a Respond to Webhook node returning {{ $json.query["hub.challenge"] }} after checking hub.verify_token.

Mind the production URL too: the test URL only works while the editor is “listening”. The URL you give Meta or your provider is the production one, active when the workflow is published.

Sample workflow: replying to incoming messages

The workflow below receives the event, separates messages from statuses, replies with text and, outside business hours, tells the customer when the team is back.

Node 1: Webhook (POST, Respond: Immediately).

Node 2: Code (Run Once for All Items mode), which turns Meta’s event into a list of messages:

const out = [];
for (const item of $input.all()) {
  const event = item.json.body ?? item.json;
  for (const entry of event.entry ?? []) {
    for (const change of entry.changes ?? []) {
      const v = change.value ?? {};
      for (const msg of v.messages ?? []) {
        out.push({
          json: {
            phone_number_id: v.metadata?.phone_number_id,
            from: msg.from,
            name: v.contacts?.[0]?.profile?.name ?? '',
            wamid: msg.id,
            type: msg.type,
            text: msg.text?.body ?? msg.interactive?.button_reply?.title ?? '',
          },
        });
      }
    }
  }
}
return out; // status-only events produce an empty list and the workflow stops here

Node 3: IF with a business-hours condition, for example {{ $now.setZone('America/New_York').hour }} between 8 and 18.

Node 4: HTTP Request (POST to the messages endpoint), with this JSON body:

{
  "messaging_product": "whatsapp",
  "to": "{{ $json.from }}",
  "type": "text",
  "text": { "body": "Hi {{ $json.name }}! We got your message and will reply shortly." }
}

This is a free-form message, and it only works because the customer just wrote to you, opening the 24-hour customer service window. To reach someone who hasn’t written, use Send Template or a body with "type": "template".

From here, the workflow can save the contact to a CRM, pass the text to an AI agent or open a ticket. For conversational flows with menus and buttons, see also Typebot with the official API and no-code automations with Make and Zapier.

How to do it with Vectalk

With Vectalk, use option 2. The native WhatsApp Trigger depends on a Meta app of your own; on Vectalk, events arrive in Meta’s format at the URL you register, and you can have several URLs per number, so n8n doesn’t compete with other systems for the webhook.

1. Publish the workflow and copy the Webhook node’s production URL.
2. Register it on Vectalk:

curl -X POST https://apis.vectalk.com.br/api/webhooks \
  -H "Authorization: Bearer $VECTALK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "instance_id": "YOUR_INSTANCE_ID",
    "url": "https://your-n8n.example.com/webhook/whatsapp",
    "name": "n8n"
  }'

1. In HTTP Request, use POST https://apis.vectalk.com.br/api/messages and a Header Auth credential named Authorization with value Bearer YOUR_TOKEN. With an instance token, the number is resolved automatically; with an organization token, include phone_number_id in the body (the Code node above already extracts it).
2. Return 200 in under 20 seconds; with Respond: Immediately, n8n does that for you.

The routes are in the webhooks and send text docs (in Portuguese). Message costs come on your Vectalk invoice, with no card at Meta. Create your account at apps.vectalk.com.br/register.

Best practices for WhatsApp workflows in n8n

• Deduplicate by wamid. The source may resend the same event. Store processed IDs (in a database or Redis) and drop repeats before replying.
• Handle statuses in a separate workflow. sent, delivered, read and failed events hit the same URL. Splitting them avoids duplicate replies and makes reporting easier; see message status via webhook.
• Don’t rely on order. Two quick messages from a customer can trigger parallel executions. If order matters, use a queue.
• Keep credentials in n8n. Never hard-code the token in a Code node or in the HTTP Request body.
• Monitor errors. Set up an Error Workflow that alerts the team when a send fails, including Meta’s error code (see WhatsApp API errors).

Frequently asked questions

Does n8n have an official node for the WhatsApp API?

Yes. n8n has the WhatsApp Business Cloud node (messages, templates and media) and the WhatsApp Trigger (account events), both connected to Meta’s Cloud API.

Can I use n8n with WhatsApp via QR code?

n8n has no native node for that. QR code integrations rely on unofficial APIs that emulate WhatsApp Web and go against WhatsApp’s Terms of Service. See official vs. unofficial API.

Why isn’t my WhatsApp Trigger receiving messages?

The usual causes are the app not being subscribed to the WABA (subscribed_apps), the test URL having overwritten the production URL, or another system having registered its own URL on the same app. The trigger section above shows how to check.

Can I send templates from n8n?

Yes, with the WhatsApp Business Cloud node’s Send Template operation or with an HTTP Request using "type": "template". The “Bad request – please check your parameters” error usually means parameters are out of order or of the wrong type for the template.

Do I need self-hosted n8n?

No. The nodes work on n8n Cloud and self-hosted. When self-hosting, your n8n URL must be public and HTTPS to receive webhooks.

---

Official sources consulted on October 25, 2026: n8n: WhatsApp Business Cloud node, n8n: WhatsApp Trigger node, n8n: WhatsApp credentials, n8n: Webhook node, n8n: WhatsApp node common issues, Meta: Cloud API webhooks, Vectalk docs: Webhooks.