⚙️ n8n COMMUNITY NODE ✔ VERIFIED

BotBee for n8n

Complete usage guide — WhatsApp automation for n8n workflows, covering every resource and operation.

📦 n8n-nodes-botbee v0.2.4 BotBee AI Labs · botbee.io

ON THIS PAGE

1. Introduction 2. Installation 3. Credential Setup 4. Quick Start 5. Node Structure 6. Operation Reference 7. AI Agents 8. Troubleshooting 9. Roadmap

Introduction

This guide explains how to use the BotBee node for n8n — a community node that connects n8n workflows directly to the BotBee WhatsApp Business API. With it, you can send messages, manage subscribers, apply labels and sequences, work with product catalogs, trigger bot flows, and even let an AI agent operate WhatsApp on your behalf.

BotBee is a WhatsApp Business API platform for sending messages, managing subscribers, labels, sequences, catalogs, and automated bot flows. n8n is a workflow automation platform that lets you connect different services together visually, without writing code for each integration.

This node exposes 30 distinct operations across 8 resource categories — everything available through BotBee's API, directly inside n8n's drag-and-drop workflow builder.

✔ Verified: n8n-nodes-botbee is a Verified Community Node — available directly on n8n Cloud and discoverable in the node search panel on self-hosted instances, no manual install required.

30
operations

8
resource categories

✔
verified node

Installation

2.1 — n8n Cloud

No installation step is needed. Since BotBee is a verified community node, it appears directly in the node search panel:

Open any workflow in your n8n Cloud instance.
Click the + to add a node, and search "BotBee."
Drag it into your workflow like any built-in node.

2.2 — Self-hosted n8n

Self-hosted instances have two ways to get the node, depending on your setup:

Option A — Search and use directly (recommended)

n8n instances show verified community nodes directly in the search panel by default, controlled by N8N_COMMUNITY_PACKAGES_ENABLED and N8N_VERIFIED_PACKAGES_ENABLED — both true by default. If "BotBee" doesn't appear when searching:

Restart your n8n instance/container — the verified node list refreshes on startup.
Confirm neither environment variable above has been set to false in your deployment.
Confirm your n8n version is recent enough to support verified-node discovery (older versions only support manual install, below).

Option B — Manual install (works on any version)

Open your n8n instance.
Go to Settings → Community Nodes.
Click "Install a community node."
Type the package name: n8n-nodes-botbee
Click Install.

Note: Manual install always works, regardless of the verified-node setting above — it's simply a second path to the same result. Community nodes must be enabled on your n8n instance (N8N_COMMUNITY_PACKAGES_ENABLED, true by default).

Setting Up Your Credential

Every operation needs a BotBee API credential attached. You only need to set this up once per n8n instance — it can then be reused across all your workflows.

Log in to your BotBee dashboard at app.botbee.io.
Find your API Token under the API / Developer settings section.
In n8n, add the BotBee node to a workflow, then click "Set up credential" under the Credential field.
Paste your API Token into the API Token field.
Click Save, then click Test to confirm the connection works.

Note: The credential only ever asks for your API Token — there is nothing else to configure.

Quick Start Example

4.1 — Send a WhatsApp text message

The fastest way to see the node work end-to-end:

Add the BotBee node to your workflow and select your BotBee API credential.
Set Resource to Message and Operation to Send Text.
Fill in Phone Number ID (from Settings → Numbers in your BotBee dashboard), Phone Number (recipient, digits only — e.g. 15557323953), and Message (e.g. "Hello! Your order #1024 has shipped.").
Execute the node.

BotBee's API responds with a status field ("1" for success, "0" for failure) and a message field describing the result:

{ "status": "1", "message": "..." }

Note: If the recipient hasn't messaged your WhatsApp number within the last 24 hours, WhatsApp's messaging policy blocks free-form text and BotBee returns status "0" with an explanatory message. See Section 8.1.

4.2 — A typical automation

A Webhook or Schedule node receives or triggers order data, a Set node maps that data onto phone_number_id, phone_number, and message, and the BotBee node sends the WhatsApp message as the final step. The same node can also be used as a tool by an AI Agent node — see Section 7.

How This Node Is Organized

Every action in this node follows the same two-step pattern:

STEP 1 — RESOURCE

What part of BotBee you want to work with (Messages, Subscribers, Labels, and so on).

STEP 2 — OPERATION

The specific action to perform within that resource (Send Text, List, Create, and so on).

Once you pick a Resource and Operation, the relevant fields appear automatically. Here's the full map — detail on every field follows in Section 6.

Resource	Ops	Includes
Message	6	Send Text, Send Interactive Buttons, Send File, Upload Media, Get Conversation, Get Delivery Status
Subscriber	6	Get, List, Create, Update, Delete, Reset Input Flow
Subscriber Chat	8	Assign to Team Member, Assign Custom Fields, Assign/Remove Labels, Assign/Remove Sequences, Add Notes, Mark Conversation Status
Label	2	List, Create
Custom Field	1	List
Template	1	List
Catalog	4	List Catalogs, List Orders, Sync, Change Order Status
Bot Flow	2	Trigger Flow, Get Post-Back List

Complete Operation Reference

Every operation available in the node, grouped by resource. Required fields are needed for the call to succeed; optional fields refine the result. Fields marked 🔽 dropdown populate live from your BotBee account once Phone Number ID (and credential) are set — no need to type raw IDs by hand.

6.1 Message

Send WhatsApp messages and check on their delivery.

Operation	Fields	What it does
Send Text	Phone Number ID, Phone Number, Message*	Sends a plain text message. Only works within WhatsApp's 24-hour session window — see Section 8.1.
Send Interactive Buttons	Phone Number ID, Phone Number, Message, Buttons (1–3), Header/Footer, Media (opt)	Message with up to 3 tappable reply buttons, optionally with an image/video/document header.
Send File	Phone Number ID, Phone Number*, Media URL or Media ID, Type, Caption	Sends an image, video, audio, or document.
Upload Media	Phone Number ID, Input Binary Field	Uploads a file from an earlier node's binary output to get a reusable Media ID for Send File.
Get Conversation	Phone Number ID, Phone Number, Limit*, Offset	Retrieves recent message history with a specific subscriber.
Get Delivery Status	WhatsApp Message ID, WhatsApp Bot ID	Checks whether a previously sent message was delivered, read, or failed.

6.2 Subscriber

Manage individual WhatsApp contacts.

Operation	Fields	What it does
Get	Phone Number ID, Phone Number*	Retrieves one subscriber's profile.
List	Phone Number ID, Limit, Offset*, Order By Most Recent	Lists subscribers for a given WhatsApp account.
Create	Phone Number ID, Name, Phone Number*	Creates a new subscriber.
Update	Phone Number ID, Phone Number*, First/Last Name, Gender, Labels	Updates an existing subscriber's profile and/or label assignment.
Delete	Phone Number ID, Phone Number*	Permanently deletes a subscriber.
Reset Input Flow	Phone Number ID, Phone Number*	Resets a subscriber out of whatever step of a bot flow they're currently in.

6.3 Subscriber Chat

Actions performed on a specific subscriber's conversation.

Operation	Fields	What it does
Assign to Team Member	Phone Number ID, Phone Number, Team Member* 🔽	Assigns the conversation to a human agent on your team. The Team Member field is a dropdown of your account's team members.
Assign Custom Fields	Phone Number ID, Phone Number*, Custom Fields (name/value pairs)	Sets custom field values on the subscriber (must match field names defined in your account — see 6.5).
Assign Labels	Phone Number ID, Phone Number, Labels* 🔽	Applies one or more labels to the subscriber. The Labels field is a dropdown populated live from your account.
Remove Labels	Phone Number ID, Phone Number, Labels* 🔽	Removes one or more labels from the subscriber.
Assign Sequences	Phone Number ID, Phone Number, Sequences* 🔽	Enrolls the subscriber into one or more automation sequences. The Sequences field is a dropdown of your account's sequences.
Remove Sequences	Phone Number ID, Phone Number, Sequences* 🔽	Removes the subscriber from one or more sequences.
Add Notes	Phone Number ID, Phone Number, Note Text*	Adds an internal note to the subscriber's chat, visible to your team only.
Mark Conversation Status NEW	Phone Number ID, Phone Number, Status (resolved / reopen / archived / unarchived / blocked / unblocked)	Marks the subscriber's conversation with a new status — e.g. resolve a support chat, archive it, or block the subscriber.

6.4 Label

Op	What it does
List	Lists all labels for a WhatsApp account. (req: Phone Number ID)
Create	Creates a new label. (req: Phone Number ID, Label Name)

6.5 Custom Field

Op	What it does
List	Lists every custom field, account-wide (not tied to one WhatsApp number). No fields required.

6.6 Template

Op	What it does
List	Lists approved templates. (req: Phone Number ID). Sending a template isn't supported yet — see Section 9.

6.7 Catalog

Operation	Fields	What it does
List Catalogs	No fields required	Lists product catalogs connected to your account.
List Orders	Catalog ID (opt — omit for all)	Lists orders placed through a catalog.
Sync ⚠️	Catalog ID*	Re-syncs catalog products from the source. Directly affects live data — cannot be undone.
Change Order Status ⚠️	Order Unique ID, Cart Status (Approved/Completed/Delivered/Refunded/Shipped)	Updates a real order's status. Cannot be undone.

6.8 Bot Flow

Operation	Fields	What it does
Trigger Flow	Phone Number ID, Phone Number, Bot Flow* 🔽	Starts a specific bot flow for a subscriber. The Bot Flow field is a dropdown of flows configured on that number.
Get Post-Back List	Phone Number ID*	Lists the postback/flow definitions configured on a WhatsApp account.

Using BotBee with AI Agents

Every operation in this node is also available as an AI-callable tool, meaning an n8n AI Agent can decide on its own, from a plain-language instruction, which BotBee action to take and what values to use — without you pre-configuring those values yourself.

💡 What this enables

A customer support AI agent could be told "send a WhatsApp confirmation to this customer" — the agent works out the phone number and message content from conversation context, then calls BotBee to actually send it.

Setting it up

Add an AI Agent node to your workflow (n8n auto-adds a chat trigger alongside it).
Attach a Chat Model to the Agent's Chat Model connector (OpenAI, Anthropic, or any model you have a credential for).
Click the + on the Agent's Tool connector, search "BotBee," and select "BotBee Tool."
Set up the BotBee credential on the tool node, same as any other BotBee node.
Choose the Resource and Operation you want the agent able to use (e.g. Message → Send Text).
For fields that should vary by user request — typically recipient and message content — click the ✨ sparkle icon next to the field and set it to "Defined automatically by the model."
Fields that should stay fixed (like your own Phone Number ID) can be left as a normal static value.

You'll see the node appear in the node picker as "BotBee Tool," listed separately from the regular "BotBee" node — standard behaviour across every AI-tool-capable node in n8n (Slack, Gmail, and others work the same way).

Note: You can add multiple BotBee Tool nodes to the same Agent, each configured for a different Resource/Operation, to give the agent a broader set of WhatsApp actions it can choose between.

Important Notes & Troubleshooting

8.1 — The 24-hour session window

WhatsApp only allows free-form messages (Send Text, Send Interactive Buttons, Send File) to a subscriber who has messaged your business number within the last 24 hours. This is a WhatsApp platform rule, not a BotBee or n8n limitation.

If a send fails with "Sending message outside 24 hour window is not allowed", either have them message the bot first to open the window, or use a Meta-approved template message instead (see Section 9).

8.2 — Irreversible operations

Two operations directly and permanently affect live data with no undo:

Catalog → Sync — re-syncs your real product catalog.
Catalog → Change Order Status — updates a real order's status.

Test these carefully, ideally against a non-critical catalog/order first.

8.3 — Dropdown fields showing no data or an error

The Team Member, Sequences, and Bot Flow fields populate live from your account. If one shows "No data," that resource genuinely has none configured yet for that Phone Number ID — check your BotBee dashboard. If one shows an error instead, make sure you're on the latest node version (Settings → Community Nodes → update), then reload the workflow.

These dropdowns show every entry, including inactive ones (labeled "inactive") — nothing is hidden.

8.4 — Getting help

For questions about this node, contact info@botbee.io. For BotBee's own API documentation, see the BotBee WhatsApp API v1 collection.

Not Yet Supported

One BotBee capability is not yet available in this node:

🚧 Send Template Message

Sending a pre-approved WhatsApp template (used to message a subscriber outside the 24-hour window). Planned for a future version.

Automate WhatsApp inside n8n

Search "BotBee" on n8n Cloud, or install n8n-nodes-botbee on self-hosted — verified and ready in minutes.

npm i n8n-nodes-botbee

Found this article helpful?

( 2 Out of 5 Found Helpful )

BotBee for n8n — Complete Usage Guide