Documentation
Connecting WhatsApp numbers to your bots.
A session is a WhatsApp number connected to Neuron. Bots send and receive on a session. Neuron supports two ways to connect a number: the official WhatsApp Cloud API (via Meta Business) and a Baileys direct connection (pairs with any WhatsApp number via QR code). Each has different setup requirements and capabilities.
Don't confuse a session with a WhatsApp Channel: a session is your connected number, whereas "WhatsApp Channels" are one-way newsletters. See the Newsletters section.
The official integration through Meta. Requires a Meta Business account, a verified WhatsApp Business phone number, and a permanent access token. Go to Settings > WhatsApp Sessions, add a Cloud API (Meta) session, and enter your Phone Number ID and Access Token.
Create a Meta Business app
Go to developers.facebook.com, create an app, and add the WhatsApp product.
Get your credentials
Copy your Phone Number ID and generate a permanent access token from the WhatsApp > API Setup page.
Configure the webhook
In your Meta app's WhatsApp webhook settings, set the callback URL to your Neuron instance: https://neuron-api.dlvh.site/api/v1/whatsapp/webhook. Use the verify token from your environment variables.
Create the session
In Neuron, go to Settings > WhatsApp Sessions, add a new Cloud API (Meta) session, and enter your credentials.
Pairs with any WhatsApp number using a QR code — no Meta Business account needed. Open Sessions, add a Direct (Baileys) session, start it, and scan the QR code with your WhatsApp mobile app.
Baileys connections use an unofficial WhatsApp protocol. They may be less stable than the official Cloud API and could be affected by WhatsApp policy changes.
If scanning a QR code is inconvenient (e.g. the phone is not nearby), you can pair using a numeric code instead. Start the Baileys session, then click "Link with Phone Number" and enter the phone number. An 8-digit pairing code appears on screen — enter it on your WhatsApp mobile app under Linked Devices > Link a Device > Link with Phone Number. The session connects without needing to scan anything.
After connecting a session, assign a bot to it. Go to the session's detail page and click "Assign Bot". Only one bot can be active per session at a time. Messages received on that session are routed to the assigned bot.
For Baileys sessions, you can start, stop, and check status. The Sessions page shows all your connections. If a session disconnects (e.g., the phone goes offline), you may need to re-scan the QR code to reconnect.
Each session maintains an event log showing connection events (connected, disconnected, QR generated), message events, and errors. View the log from the session detail page to debug connection issues or track session health.
For connected Baileys sessions, you can view all WhatsApp groups the number is participating in, see group participants, and browse the phone's WhatsApp contacts — all from the session detail page. This is useful for setting up group whitelists on bots or syncing contacts into your Neuron database.