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

# Connect Zalo Official Account to ChatbotX in 5 Steps

> Connect your Zalo Official Account to ChatbotX: create a Zalo developer app, configure credentials, verify your domain, and subscribe webhook events.

Zalo OA (Official Account) is Vietnam's most popular business messaging channel. Connecting your Zalo OA to ChatbotX lets you manage customer conversations, build automated Flows, and deploy AI Agents — all from the same unified inbox you use for WhatsApp, Messenger, and other channels.

## Prerequisites

Before you begin, make sure you have:

* Admin access to your ChatbotX installation
* A Zalo OA (Official Account) with admin privileges
* A Zalo Developer account with admin privileges at [Zalo Developers](https://developers.zalo.me/)
* A valid Vietnamese mobile phone number

<Note>
  Zalo OA is a popular messaging channel in Vietnam. A Vietnamese mobile phone number is required to register on the Zalo Developer platform.
</Note>

***

## Step 1: Create a Zalo Application

If you do not have a Zalo application yet, create one on the Zalo Developer platform before connecting to ChatbotX.

<Steps>
  <Step title="Register on Zalo Developers">
    Go to [Zalo Developers](https://developers.zalo.me/) and sign in with your Zalo account. If you don't have a developer account, register one using your Vietnamese phone number.
  </Step>

  <Step title="Create a new application">
    Follow the [official Zalo documentation](https://developers.zalo.me/docs/official-account/bat-dau/khoi-tao-ung-dung) to create a new application. Provide your application name and description.
  </Step>

  <Step title="Activate the application">
    After the application is created, set its status to **Active** in the application dashboard.
  </Step>

  <Step title="Copy App ID and Secret Key">
    In your Zalo application dashboard, locate the **Application ID** and **Application's Private Key**. Copy these values — you will need them in the next step.
  </Step>

  <Step title="Enable required APIs">
    Navigate to the API settings in your Zalo application and enable the required APIs.
  </Step>
</Steps>

***

## Step 2: Configure Credentials in ChatbotX

A Super Admin must enter the Zalo credentials in ChatbotX before the integration can work. Complete this step immediately after obtaining your App ID and Secret Key.

<Steps>
  <Step title="Open Integrations">
    In your ChatbotX installation, navigate to:

    ```text theme={null}
    https://app.yourdomain.com/admin/platform-credentials
    ```

    Then find the **Zalo** card.
  </Step>

  <Step title="Open the Zalo configuration">
    Click the **Edit** button on the Zalo card to open the configuration modal.
  </Step>

  <Step title="Fill in the Zalo credentials">
    In the **Edit Zalo** modal, fill in the following fields:

    | Field                    | Description                         | Where to find                   |
    | ------------------------ | ----------------------------------- | ------------------------------- |
    | **Client ID**            | Zalo **Application ID**             | Zalo Developers → App Dashboard |
    | **Client Secret**        | Zalo **Application's Private Key**  | Zalo Developers → App Dashboard |
    | **API Version**          | API version to use                  | For example, `v1.0`             |
    | **Webhook Verify Token** | A unique string you create yourself | Self-generated                  |

    <Note>
      The **Webhook Verify Token** is a unique string you generate yourself. Zalo uses this token to verify that webhook requests are coming from your server.
    </Note>
  </Step>

  <Step title="Save">
    Click **Save** to apply the settings. The Zalo card will now display your **Client ID**.

    After saving, ChatbotX will display the **Auth Callback URL** and **Webhook URL**. Copy and keep these URLs — you will need them in the following steps.
  </Step>
</Steps>

***

## Step 3: Verify Your Domain

Zalo requires domain verification before your application can receive webhook events. This step confirms that you own the domain where ChatbotX is hosted.

<Steps>
  <Step title="Identify your ChatbotX domain">
    The domain you need to verify is the one that hosts your ChatbotX installation, for example:

    ```text theme={null}
    app.yourdomain.com
    ```
  </Step>

  <Step title="Complete domain verification in Zalo">
    Go to your Zalo application settings and follow the [Zalo domain verification guide](https://developers.zalo.me/docs/official-account/phu-luc/huong-dan-xac-thuc-domain). Add the meta tag obtained from Zalo to your ChatbotX domain's HTML or DNS settings.
  </Step>

  <Step title="Confirm verification status">
    Domain verification may take a few seconds to propagate. Check the verification status in your Zalo application dashboard after 3–5 seconds. You may need to check 2–3 times before the status updates.
  </Step>
</Steps>

***

## Step 4: Configure Callback and Webhook URLs

ChatbotX needs two URLs configured in your Zalo application to receive messages and events.

<Steps>
  <Step title="Set the Callback URL in Zalo">
    Copy the **Auth Callback URL** from your ChatbotX Zalo integration settings, then paste it into your Zalo application settings and select the required permissions for OAuth authorization.
  </Step>

  <Step title="Set the Webhook URL in Zalo">
    Copy the **Webhook URL** from your ChatbotX Zalo integration settings, then paste it into your Zalo application's webhook configuration. Subscribe to the following events:

    | Event      | Description                               |
    | ---------- | ----------------------------------------- |
    | `send_msg` | Triggered when your OA sends a message    |
    | `get_msg`  | Triggered when your OA receives a message |
    | `follow`   | Triggered when a user follows your OA     |
    | `unfollow` | Triggered when a user unfollows your OA   |
  </Step>
</Steps>

***

## Step 5: Connect Zalo OA to ChatbotX

<Steps>
  <Step title="Add your Zalo OA">
    In the ChatbotX Zalo integration settings, click **Add Zalo OA**.
  </Step>

  <Step title="Authorize the connection">
    You will be redirected to Zalo's authorization page. Confirm the permissions and authorize ChatbotX to access your Zalo OA.
  </Step>

  <Step title="Verify the connection">
    After authorization, return to ChatbotX. Your Zalo OA should be listed as a connected channel in the dashboard.
  </Step>
</Steps>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Messages not appearing in ChatbotX">
    * Verify that the Webhook URL is correctly configured in your Zalo application
    * Check that all required webhook events are subscribed: `send_msg`, `get_msg`, `follow`, `unfollow`
    * Confirm the **Webhook Verify Token** matches between ChatbotX and Zalo
  </Accordion>

  <Accordion title="Domain verification failing">
    * Ensure your ChatbotX server is accessible via HTTPS
    * Wait 3–5 seconds between verification attempts
    * Try an alternative verification method (DNS TXT record vs meta tag)
  </Accordion>

  <Accordion title="Authorization errors">
    * Make sure you are logged into the correct Zalo account with admin access to the OA
    * Check that the Callback URL is correctly set in your Zalo application
    * Verify the **Client ID** and **Client Secret** in ChatbotX match the App ID and Secret Key in Zalo
  </Accordion>

  <Accordion title="How do I get help if the issue persists?">
    1. Check the ChatbotX server logs for error messages
    2. Verify all credentials in the platform credentials panel are correctly configured
    3. Ensure your Zalo OA and developer accounts meet the prerequisites
    4. Contact Community support with specific error messages if the issue persists
  </Accordion>
</AccordionGroup>