diff --git a/docs/chat-apps.md b/docs/chat-apps.md
index c67f8adc..26531e15 100644
--- a/docs/chat-apps.md
+++ b/docs/chat-apps.md
@@ -343,6 +343,12 @@ Optional session database path:
 }
 ```
 
+**Migrating from the old bridge**
+
+- Remove `bridgeUrl` and `bridgeToken`; WhatsApp no longer runs a local Node.js bridge.
+- Re-run `nanobot channels login whatsapp`; old Baileys bridge auth data is not reused by neonize.
+- Update `allowFrom` entries to the WhatsApp sender ID without a leading `+`.
+
 **3. Run**
 
 ```bash
diff --git a/nanobot/channels/whatsapp.py b/nanobot/channels/whatsapp.py
index 3a5bec03..9e7e3e6f 100644
--- a/nanobot/channels/whatsapp.py
+++ b/nanobot/channels/whatsapp.py
@@ -50,12 +50,17 @@ class _MediaInfo(NamedTuple):
 
 _NEONIZE_API: _NeonizeAPI | None = None
 _JID_RE = re.compile(r"^(?P<user>[^@]+)@(?P<server>[^@]+)$")
+_LEGACY_BRIDGE_CONFIG_FIELDS = ("bridgeUrl", "bridgeToken", "bridge_url", "bridge_token")
 
 
 def _default_database_path() -> Path:
     return get_runtime_subdir("whatsapp-auth") / "neonize.db"
 
 
+def _legacy_bridge_config_fields(config: dict[str, Any]) -> list[str]:
+    return [field for field in _LEGACY_BRIDGE_CONFIG_FIELDS if field in config]
+
+
 def _load_neonize() -> _NeonizeAPI:
     global _NEONIZE_API
     if _NEONIZE_API is not None:
@@ -272,9 +277,16 @@ class WhatsAppChannel(BaseChannel):
         return WhatsAppConfig().model_dump(by_alias=True)
 
     def __init__(self, config: Any, bus: MessageBus):
+        legacy_bridge_fields = _legacy_bridge_config_fields(config) if isinstance(config, dict) else []
         if isinstance(config, dict):
             config = WhatsAppConfig.model_validate(config)
         super().__init__(config, bus)
+        if legacy_bridge_fields:
+            self.logger.warning(
+                "Ignoring deprecated WhatsApp bridge config fields: {}. "
+                "Run 'nanobot channels login whatsapp' to create a neonize session.",
+                ", ".join(legacy_bridge_fields),
+            )
         self._client: Any | None = None
         self._connected = False
         self._processed_message_ids: OrderedDict[str, None] = OrderedDict()
diff --git a/tests/channels/test_whatsapp_channel.py b/tests/channels/test_whatsapp_channel.py
index 6d58f7a9..e3eee242 100644
--- a/tests/channels/test_whatsapp_channel.py
+++ b/tests/channels/test_whatsapp_channel.py
@@ -8,7 +8,7 @@ import pytest
 
 from nanobot.bus.events import OutboundMessage
 from nanobot.channels import whatsapp as whatsapp_module
-from nanobot.channels.whatsapp import WhatsAppChannel, _NeonizeAPI
+from nanobot.channels.whatsapp import WhatsAppChannel, _legacy_bridge_config_fields, _NeonizeAPI
 
 
 class _Proto:
@@ -123,6 +123,11 @@ def test_default_config_has_no_bridge_fields() -> None:
     assert config["databasePath"] == ""
 
 
+def test_legacy_bridge_config_fields_are_detected() -> None:
+    assert _legacy_bridge_config_fields({"bridgeUrl": "ws://localhost:3001"}) == ["bridgeUrl"]
+    assert _legacy_bridge_config_fields({"bridgeToken": "secret"}) == ["bridgeToken"]
+
+
 @pytest.mark.asyncio
 async def test_login_succeeds_when_connected(monkeypatch) -> None:
     _patch_neonize_api(monkeypatch)