> ## Documentation Index
> Fetch the complete documentation index at: https://chatbotx.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# WhatsApp Conversation Orchestration

> Configure WhatsApp Conversation Orchestration in ChatbotX to coordinate between partner bots and human agents on a single WhatsApp number.

**WhatsApp Conversation Orchestration** allows a single WhatsApp Business phone number to connect and operate across multiple technology partner integrations simultaneously on the same account.

You need this feature when using a third-party AI bot to handle initial customer inquiries while connecting ChatbotX for human agents to take over complex conversations in Live Chat without message conflicts.

## Core Conversation Thread States

Under Meta's conversation orchestration model, any conversation between a customer and your WhatsApp phone number always belongs to one of three states:

<CardGroup cols={3}>
  <Card title="Standby" icon="pause">
    Another partner owns the conversation. The ChatbotX message box is safely locked to prevent duplicate replies.
  </Card>

  <Card title="Owned" icon="play">
    ChatbotX has active ownership. Agents can freely send direct messages to the contact in Live Chat.
  </Card>

  <Card title="Idle" icon="rotate-right">
    No partner currently owns the conversation. The next customer message determines which partner responds.
  </Card>
</CardGroup>

The table below outlines permissions across the three states:

| Thread State | Conversation Owner | ChatbotX Composer Status | Messaging Permissions |
| - | - | - | - |
| **Standby** | Third-party partner | Safely locked | Read-only, cannot send service messages |
| **Owned** | ChatbotX (Agent) | Fully unlocked | Can send direct service messages |
| **Idle** | None | Waiting | Waiting for the next inbound message |

## Configure Handover Resume Flow

When a third-party partner encounters an unanswerable question or a contact requests human assistance, that partner passes thread control to ChatbotX. You can configure an automated flow to greet contacts and collect details immediately upon receiving control.

<Steps>
  <Step title="Access WhatsApp channel settings">
    From the left navigation menu, go to **Settings > Channels**. In the list of connected WhatsApp numbers, click **Manage** next to the phone number you want to configure.

    <Frame>
      <img src="https://mintcdn.com/chatbotx/7jNRuCKvyH4muUDg/images/whatsapp_channels_settings_manage.png?fit=max&auto=format&n=7jNRuCKvyH4muUDg&q=85&s=a49f283f12d7fdbe8a05e9908c2b2cc9" alt="Whatsapp Channels Settings Manage" width="3026" height="1666" data-path="images/whatsapp_channels_settings_manage.png" />
    </Frame>
  </Step>

  <Step title="Select a handover flow">
    Switch to the **Settings** tab, scroll down to the **Automation** section, and locate **Handover resume flow**. Under **Choose a flow**, select the automated flow you want to trigger when control is handed back.
  </Step>

  <Step title="Save changes">
    Click **Save changes** to complete the setup. The system displays a confirmation notification.

    <Frame>
      <img src="https://mintcdn.com/chatbotx/7jNRuCKvyH4muUDg/images/whatsapp_handover_resume_flow_settings.png?fit=max&auto=format&n=7jNRuCKvyH4muUDg&q=85&s=806fbb94d93427cd91a83ea86b22c0d5" alt="Whatsapp Handover Resume Flow Settings" width="3034" height="1650" data-path="images/whatsapp_handover_resume_flow_settings.png" />
    </Frame>
  </Step>
</Steps>

<Note>
  When a partner hands control back, ChatbotX automatically pins the conversation summary and chat history inside Live Chat so agents understand context immediately without reading through older message threads.
</Note>

## Manage Conversations in Inbox

### Standby Mode While Another Partner Responds

When a third-party partner owns the conversation, ChatbotX automatically enters passive listening mode:

* The contact list displays an orange badge labeled **Standby (Partner)**.
* The **Conversation routing** panel on the right sidebar displays the `Standby` state and `Standby - listening only` role.
* The central chat area displays a warning banner and locks the message composer to prevent duplicate customer replies.

<Frame>
  <img src="https://mintcdn.com/chatbotx/7jNRuCKvyH4muUDg/images/whatsapp_inbox_standby_take_over.png?fit=max&auto=format&n=7jNRuCKvyH4muUDg&q=85&s=59bcea3239e86cb76c499215b8651728" alt="Whatsapp Inbox Standby Take Over" width="3778" height="1890" data-path="images/whatsapp_inbox_standby_take_over.png" />
</Frame>

### Take Over Conversation Control

When human intervention is urgently required, agents can take over conversation ownership immediately:

* Click **Take over** on the bottom warning banner, or directly send a message from the Inbox.
* The system invokes escalation privileges, reclaims ownership from the previous partner, and transitions the thread to **Owned**.
* The contact badge changes to blue **Active**, and the message composer unlocks completely for real-time conversation.

<Frame>
  <img src="https://mintcdn.com/chatbotx/7jNRuCKvyH4muUDg/images/whatsapp_inbox_owned_active_release.png?fit=max&auto=format&n=7jNRuCKvyH4muUDg&q=85&s=a3ff15d62720fd0c8f0056f572a4b0e7" alt="Whatsapp Inbox Owned Active Release" width="3779" height="1888" data-path="images/whatsapp_inbox_owned_active_release.png" />
</Frame>

### Release Conversation After Resolution

After resolving the contact inquiry, release the thread back to Idle so automated entry flows can resume:

* Click **Release** on the top header toolbar.
* The system displays a confirmation notification that the conversation has been released.
* The thread transitions to **Idle** with the role `Idle - waiting`. The next inbound customer message routes according to your business entry-point settings without waiting for the 24-hour inactivity timeout.

<Frame>
  <img src="https://mintcdn.com/chatbotx/7jNRuCKvyH4muUDg/images/whatsapp_inbox_idle_released.png?fit=max&auto=format&n=7jNRuCKvyH4muUDg&q=85&s=21d16b06c3ed37ebf921e581e2652eb3" alt="Whatsapp Inbox Idle Released" width="3780" height="1891" data-path="images/whatsapp_inbox_idle_released.png" />
</Frame>

## Messaging Rules and Platform Policies

<Warning>
  Under Meta policy, only the current thread owner can send free-form 24-hour service messages. Any partner currently on Standby attempting to send service messages will be rejected by Meta.
</Warning>

Pre-approved template messages (marketing, authentication, and utility) can be sent by any authorized partner at any time without altering conversation ownership.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.