WhatsApp Agent

Connect one WhatsApp route to a ChatNexus chatbot using Twilio or the Meta Cloud API.

WhatsApp Agent

The WhatsApp agent lets customers message a ChatNexus chatbot on WhatsApp. A chatbot uses one active WhatsApp route at a time. You can retain provider credentials while testing, but enabling a different provider makes that provider the active route for the chatbot.

Choose a connection method

There are three WhatsApp choices in the dashboard. Select the one that matches where your sender is managed:

| Dashboard choice | Use it when | | --- | --- | --- | | Facebook Easy setup | ChatNexus should guide you through Meta's embedded signup. This is still a preview while ChatNexus completes Meta Tech Provider review. | | Facebook Existing setup | Your WhatsApp Business Account and phone are already registered in Meta, and you have the Meta Cloud API credentials. | | Twilio | Your WhatsApp sender is managed in Twilio. |

Facebook Existing setup and Twilio — available now

Use Facebook Existing setup when your business already has a Meta registration. Use Twilio when the sender is managed in Twilio. These are separate provider paths: Meta tokens do not work in Twilio fields, and Twilio credentials do not work in Facebook fields.

  • Facebook Existing setup — enter the public WhatsApp Business phone number, WABA ID, Phone Number ID, and a Meta access token. ChatNexus can sync authorized phone numbers, templates, and webhook subscriptions.
  • Twilio — enter the Twilio Account SID, Auth Token, and registered WhatsApp sender. Use a production WhatsApp sender, or follow Twilio's Sandbox join instructions while testing.

Facebook Easy setup — preview

Once ChatNexus completes Meta Tech Provider review, a new business will be able to create and connect its WhatsApp Business Account through a guided Meta Embedded Signup. The business owner will still need to sign in to Meta, accept permissions, and verify phone ownership; ChatNexus will handle the account linking, webhook connection, and profile setup.

Until that approval is complete, new users cannot provision a WABA through ChatNexus. They must use Facebook Existing setup or Twilio.

Facebook Existing setup (Meta Cloud API)

1

Enable the WhatsApp agent

In Agents, select WhatsApp and enable the agent.

2

Open Facebook Existing setup

Select Facebook Existing setup. This is the manual path for a WhatsApp registration that already exists in Meta.

3

Add the business credentials

Enter the public WhatsApp Business phone number, WABA ID, Phone Number ID, and a valid Meta access token. Save the configuration.

4

Verify and sync

Select Verify & Sync. ChatNexus reads the business assets that the token is authorized to manage, activates the Meta connection, and lists phone numbers, templates, and existing webhook subscriptions.

5

Configure and subscribe the webhook

In Meta, save the displayed callback URL and verify token under Production setup → Configure Webhooks. Back in ChatNexus, select Subscribe ChatNexus Webhook. Confirm that ChatNexus appears in the WABA webhook subscriptions list.

6

Test with a real approved recipient

For a Meta test number, add your WhatsApp number as an approved test recipient in Meta. Send a message from that number to the test number and confirm both the inbound message and the chatbot reply.

Where to find the Facebook Existing setup values

  • WhatsApp Business phone number — the number customers will message, including its country code. This is not the Phone Number ID.
  • WABA ID — in Meta Business Settings → Accounts → WhatsApp Accounts, open the relevant WhatsApp Business Account and copy its ID.
  • Phone Number ID — in Meta WhatsApp Manager → Phone numbers, open the registered number and copy the numeric Phone Number ID shown for API use.
  • Access token — create or copy a Meta token that has access to this WABA and includes whatsapp_business_management and whatsapp_business_messaging. Never paste an app secret or a token from a different business.

If you do not already have these values, choose Facebook Easy setup only when it is available for your account; otherwise complete the Meta registration first or use Twilio.

One sender number, one chatbot

A WhatsApp Phone Number ID can be assigned to only one ChatNexus chatbot at a time. The rule applies to production numbers and Meta test numbers alike.

  • To test two chatbots at the same time, use two different sender numbers.
  • Disconnecting a number removes its ChatNexus assignment; it does not delete the number or WABA in Meta.
  • If another chatbot tries to connect a number that is already assigned, ChatNexus should identify the chatbot currently using it. Disconnect it there before reconnecting.
  • Switching a number to another chatbot changes which chatbot receives future messages; it does not merge the old chatbot's conversations or knowledge base.

Switch a connected number safely

ChatNexus does not silently move a live sender when a second chatbot tries to claim it. This prevents a customer's message from reaching the wrong knowledge base.

  1. Open the chatbot that currently owns the number.
  2. Open Agents → WhatsApp, select the matching provider, and choose Disconnect number.
  3. Wait for the success message confirming that the number is unassigned from ChatNexus. This normally takes effect immediately; ChatNexus does not impose a cooling-off period.
  4. Open the new chatbot, select the same provider, and save or complete the connection there.

Disconnecting in ChatNexus only removes the ChatNexus route. It does not delete the number, WABA, Twilio account, Meta registration, templates, or provider webhook. Provider-side migration rules are separate: Meta or Twilio may still require verification, registration, an approved template, or a webhook update.

The Connection Status card shows which provider is active. A provider can remain configured but inactive while the other provider is active; only the active provider receives new WhatsApp messages for that chatbot. ChatNexus refuses ambiguous Twilio claims and ignores a Meta webhook whose Phone Number ID does not match the configured chatbot.

Testing more than one chatbot

For two chatbots to receive messages at the same time, use two sender numbers or two separately configured provider assets. A Meta public test number can be shared by Meta's own developer accounts, but ChatNexus still treats that sender as one route at a time. Two ChatNexus chatbots cannot safely listen to the same test sender simultaneously.

Meta test numbers and templates

Meta test senders are controlled by the Meta developer app and test WABA that created them. Meta controls which recipient numbers may receive test messages and which templates can be sent. A test sender can prove the integration, but it is still one sender asset inside ChatNexus and cannot be assigned to two chatbots at once.

For a business-initiated message, use an approved Meta template. A free-form reply normally works after the recipient messages the business number and the customer-service window is open. The common Hello World template is restricted to Meta's public test numbers; it is not a general-purpose template for a registered business number.

Profile images and message delivery

The chatbot logo in Settings → Identity & General controls the ChatNexus web embed and chatbot list. The WhatsApp Business profile photo is owned by Meta or Twilio and is managed in that provider's business profile settings. Changing the web logo does not automatically change the provider profile photo.

Incoming messages are routed by the sender's Phone Number ID and provider configuration to the assigned chatbot. The chatbot's model, system prompt, knowledge base, media settings, and session state are then used. Live View should show one inbound message and one assistant response for each unique WhatsApp message ID; provider retries are ignored through message-id idempotency.

Twilio production setup

The Twilio Sandbox is for development only. To use a branded business number:

  1. Upgrade the Twilio account and start WhatsApp Sender Self Sign-up in Twilio Console.
  2. Register a Twilio number, or a number that can receive an SMS or voice OTP and is not already registered with WhatsApp.
  3. Create or select the Meta Business Portfolio and create the WABA through Twilio for the first sender.
  4. Complete Meta business verification, configure the inbound webhook in Twilio, then save the production sender in ChatNexus.

What ChatNexus supports

  • AI replies to inbound messages
  • Media-aware messages, including images and documents where supported
  • Saved conversation threads and live handoff
  • Meta Business asset visibility for an authorized WABA
  • Manual provider credentials today and guided Tech Provider onboarding after approval