WhatsApp Coexistence Mode

Overview

Coexistence mode allows businesses to use WhatsApp Business App (mobile) and Cloud API (automated) simultaneously on the same phone number, with bidirectional message synchronization.

This is ideal for businesses that want to:

Maintain manual control via the WhatsApp Business App for personalized interactions
Leverage AI automation via Moveo's Cloud API integration for scalable support
Keep message history synced across both platforms

Which setup path should I follow?

Your situation	Setup path
Setting up WhatsApp for the first time	New integration setup - Enable coexistence during embedded signup
Already have a Moveo WhatsApp integration	Existing integration setup - Re-run embedded signup selecting WhatsApp Business App

New integrations

If you're setting up WhatsApp for the first time and want coexistence, follow the standard WhatsApp Business setup. During embedded signup, when the Meta modal asks you to select a WhatsApp account type, choose WhatsApp Business App to enable coexistence automatically.

Prerequisites

Before enabling coexistence mode, ensure you have:

✅ Meta-approved BSP with coexistence capability

Moveo.AI is a Meta Tech Partner with coexistence support

✅ Business verification

PLBV (Phone-Level Business Verification) or Meta Verified status

✅ Supported region

❌ Nigeria and South Africa are not supported for coexistence

✅ WhatsApp Business App installed

Installed on your mobile device

Setup for new integrations

Navigate to Integrations in your Moveo account
Select your environment
Click Configure on the WhatsApp card
Follow the embedded signup flow
Key step: When the Meta modal asks you to select a WhatsApp account type, choose WhatsApp Business App — this enables coexistence automatically
Enter your existing WhatsApp Business App phone number
Meta displays a QR code → Scan with WhatsApp Business App
Accept the consent screen (optionally enable history sharing)

Setup for existing integrations

Step 1: Check eligibility

Requirement	Status
Meta-approved BSP with coexistence capability	✅ Moveo.AI is Meta Tech Partner
Business verification (PLBV or Meta Verified)	Must verify
Region supported	❌ Nigeria, South Africa not supported

Install WhatsApp Business App on phone (if not already)
Go to Integrations → WhatsApp → Configure and start the embedded signup flow
Key step: When the Meta modal asks you to select a WhatsApp account type, choose WhatsApp Business App — this enables coexistence automatically
Enter your existing phone number
Scan QR code displayed by Meta
Accept consent screen

How it works

Message flow

When coexistence mode is enabled, messages flow bidirectionally:

Customer sends message
    ↓
Both WhatsApp Business App AND Cloud API receive it
    ↓
AI agent responds via Cloud API (appears in App)
    ↓
Human agent replies via App
    ↓
AI agent is paused — new bot sessions are blocked for this user
    ↓
Message visible in Human Chat with 📱 icon
    ↓
Human agent sends reset command → AI agent resumes on next user message

Messages are visible to the end user

All messages sent from the WhatsApp Business App — including the reset command — are delivered to the end user's WhatsApp chat. There is no way to send a "hidden" message from the Business App. For this reason, you can configure a custom reset command that looks natural in conversation.

Key behaviors

Scenario	Behavior
Human agent replies via App	AI agent pauses (handover), message recorded in Human Chat with 📱 icon
Human agent sends location	Recorded as "Shared location: {name}"
Human agent sends contact	Recorded as "Shared contact: {name}"
Session expired	Message still reaches user, just not tracked in Moveo
No active session	AI agent session creation is blocked until the coexistence timeout expires or the human agent resets

Handing back to the AI agent

When the human agent is done and wants the AI agent to resume, they send the reset command from the WhatsApp Business App. This removes the block on the AI agent, so the next message from the end user will create a fresh session handled by the bot.

The default reset command is /reset, but you can configure a custom command text (e.g., done, handoff) to make it look more natural to the end user, since the message is visible in their chat. The matching is case-insensitive and ignores leading/trailing whitespace.

Rule required

For the AI agent to automatically handle the conversation after the reset command, you must have a rule with the trigger "A customer starts a conversation" that assigns the AI agent. After the reset, the next user message creates a new session — this trigger ensures the bot is assigned to it. See Rules for setup instructions.

Reset command is not recorded

The reset command is treated as a control message — it is not saved in the session history. However, it is still visible to the end user as a regular WhatsApp message.

Setting	Default	Description
`coexistence_reset_text`	`/reset`	The command text the human agent sends to reset. Can be customized to any text. Set to empty to disable.
`coexistence_timeout`	7 days	How long the AI agent stays paused without a reset

Verification checklist

Pre-setup

Business is verified (PLBV or Meta Verified)
Region is supported
WhatsApp Business App installed on device

Post-setup

Coexistence enabled via embedded signup (selected WhatsApp Business App)
Test: Send message from App → appears in Human Chat with 📱 icon
Test: Session hands over when agent replies via App

Limitations

Limitation	Impact
No OBA/Blue Badge	Not available for coexistence accounts
Broadcast lists disabled	Must use API for broadcasts
Companion devices unsupported	Windows/WearOS devices cannot be linked
14-day media limit	Older media cannot sync

Troubleshooting

No 📱 icon on messages

Cause: is_coexistence flag not saved properly

Solution: Re-save the integration settings in Moveo with coexistence mode enabled

"Session not found" warnings in logs

Cause: Normal for conversations that started before coexistence was enabled

Solution: This is expected behavior. New conversations will be tracked properly.

Messages from Windows/WearOS missing

Cause: Companion devices (Windows, WearOS) are not supported in coexistence mode

Solution: Use the phone app only for sending messages

Reset command not working

Symptoms: The human agent sends the reset command from the WhatsApp Business App but the AI agent doesn't resume.

Possible causes:

The end user hasn't sent a new message yet. The reset command unblocks the AI agent, but the bot only resumes when the end user sends their next message (which creates a fresh session). This is expected behavior.
The command text doesn't match. The reset text must match the configured coexistence_reset_text value (default: /reset). The match is case-insensitive, but the content must match — for example, if the default is /reset, sending reset without the slash won't work.
Reset is disabled. If coexistence_reset_text is set to an empty string, the reset command is disabled entirely. The AI agent will only resume after the coexistence timeout expires.

Resources

Official documentation

Support

Meta Business Help Center
Moveo support: support@moveo.ai

Next steps

Once coexistence mode is enabled:

Test the integration - Send a message from the WhatsApp Business App and verify it appears in Human Chat with the 📱 icon
Train your team - Ensure agents understand that replying via the App will trigger a handover
Configure your AI Agent - See WhatsApp Business for profile customization and message templates

Overview​

Which setup path should I follow?​

Prerequisites​

Setup for new integrations​

Embedded Signup with Coexistence​

Setup for existing integrations​

Step 1: Check eligibility​

Step 2: Re-run embedded signup​

How it works​

Message flow​

Key behaviors​

Handing back to the AI agent​

Verification checklist​

Pre-setup​

Post-setup​

Limitations​

Troubleshooting​

Resources​

Official documentation​

Support​

Next steps​