> ## 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.

# Zalo Official Account

> Connect your Zalo Official Account to ChatbotX so your chatbot can send and receive messages on Zalo.

## 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.

    <Frame>
      <img src="https://mintcdn.com/chatbotx/ILDlPWyJuzzPj7RT/images/image-282.png?fit=max&auto=format&n=ILDlPWyJuzzPj7RT&q=85&s=68f805c84557626575c9d9fa8d39b3b2" alt="zalo_developers_portal_homepage_login" width="2994" height="1588" data-path="images/image-282.png" />
    </Frame>
  </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.

    <Frame>
      <img src="https://mintcdn.com/chatbotx/ILDlPWyJuzzPj7RT/images/image-283.png?fit=max&auto=format&n=ILDlPWyJuzzPj7RT&q=85&s=dce36c89f323506b892f88f884976846" alt="zalo_developers_create_new_application_form" width="3004" height="1476" data-path="images/image-283.png" />
    </Frame>
  </Step>

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

    <Frame>
      <img src="https://mintcdn.com/chatbotx/ILDlPWyJuzzPj7RT/images/image-284.png?fit=max&auto=format&n=ILDlPWyJuzzPj7RT&q=85&s=c7dae0789f9110de017c42111f9c6632" alt="zalo_developers_application_status_active" width="3010" height="1530" data-path="images/image-284.png" />
    </Frame>
  </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.

    <Frame>
      <img src="https://mintcdn.com/chatbotx/ILDlPWyJuzzPj7RT/images/image-285.png?fit=max&auto=format&n=ILDlPWyJuzzPj7RT&q=85&s=5e68f2baa5af270f79e178c88f2adde5" alt="zalo_app_dashboard_app_id_secret_key" width="3010" height="1530" data-path="images/image-285.png" />
    </Frame>
  </Step>

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

    <Frame>
      <img src="https://mintcdn.com/chatbotx/ILDlPWyJuzzPj7RT/images/image-286.png?fit=max&auto=format&n=ILDlPWyJuzzPj7RT&q=85&s=fcb64b1a1a16e49037e8bbf8fb31ad30" alt="zalo_app_api_settings_enabled_apis_list" width="2925" height="1841" data-path="images/image-286.png" />
    </Frame>
  </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/manage/integrations
    ```

    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.

    <Frame>
      <img src="https://mintcdn.com/chatbotx/ILDlPWyJuzzPj7RT/images/image-287.png?fit=max&auto=format&n=ILDlPWyJuzzPj7RT&q=85&s=259b9521d72295379e01aaec171f369a" alt="chatbotx_edit_zalo_modal" width="2300" height="1548" data-path="images/image-287.png" />
    </Frame>
  </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                 | e.g., `v1.0`                    |
    | **Webhook Verify Token** | Any string you create yourself     | Self-generated                  |

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

    <Frame>
      <img src="https://mintcdn.com/chatbotx/ILDlPWyJuzzPj7RT/images/image-288.png?fit=max&auto=format&n=ILDlPWyJuzzPj7RT&q=85&s=b892d5d5ef42cc362da6252439037e70" alt="fill-in-the-zalo-credentials" width="2291" height="1512" data-path="images/image-288.png" />
    </Frame>
  </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.

    <Frame>
      <img src="https://mintcdn.com/chatbotx/w6VS-GzWGWlJyR_i/images/image-307.png?fit=max&auto=format&n=w6VS-GzWGWlJyR_i&q=85&s=fe387d8e5851251b53a8c630e14686a1" alt="Image" width="1170" height="808" data-path="images/image-307.png" />
    </Frame>
  </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="Get the verification URL from ChatbotX">
    Copy the domain that directs to your ChatbotX Org Settings panel. This is the domain where your ChatbotX application is hosted and will be used for domain verification:

    ```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.

    <Frame>
      <img src="https://mintcdn.com/chatbotx/tyPKYprKEiHEDyz2/images/image-308.png?fit=max&auto=format&n=tyPKYprKEiHEDyz2&q=85&s=4a109748b60ee5ae9e293b5cf8f60fa7" alt="zalo_developers_domain_verification_meta_tag_setup" width="3808" height="1814" data-path="images/image-308.png" />
    </Frame>
  </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.

    <Frame>
      <img src="https://mintcdn.com/chatbotx/tyPKYprKEiHEDyz2/images/image-309.png?fit=max&auto=format&n=tyPKYprKEiHEDyz2&q=85&s=8360a1ee1dc3f63aba61992cfddcfc44" alt="zalo_developers_domain_verification_status_confirmed" width="3530" height="1688" data-path="images/image-309.png" />
    </Frame>
  </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.

    <Frame>
      <img src="https://mintcdn.com/chatbotx/gwEdLyxU_QvH0ENX/images/image-292.png?fit=max&auto=format&n=gwEdLyxU_QvH0ENX&q=85&s=d70db9af54f71626256f4caf131b4dbf" alt="zalo_app_settings_callback_url_permissions_configuration" width="3000" height="1600" data-path="images/image-292.png" />
    </Frame>
  </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:

    ```text theme={null}
    send_msg
    get_msg
    follow
    unfollow
    ```

    <Frame>
      <img src="https://mintcdn.com/chatbotx/gwEdLyxU_QvH0ENX/images/image-293.png?fit=max&auto=format&n=gwEdLyxU_QvH0ENX&q=85&s=2c1d05952fd5fe2399845fe7d4265237" alt="zalo_app_webhook_url_event_subscriptions" width="3014" height="1422" data-path="images/image-293.png" />
    </Frame>
  </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**.

    <Frame>
      <img src="https://mintcdn.com/chatbotx/mhgfnsJNBDee95jD/images/image-294.png?fit=max&auto=format&n=mhgfnsJNBDee95jD&q=85&s=159117fd074f3a83cb47ddda77772785" alt="chatbotx_zalo_integration_select_oa_account" width="3026" height="1395" data-path="images/image-294.png" />
    </Frame>
  </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.

    <Frame>
      <img src="https://mintcdn.com/chatbotx/mhgfnsJNBDee95jD/images/image-295.png?fit=max&auto=format&n=mhgfnsJNBDee95jD&q=85&s=f8ec40221be51a184d160b64c192178c" alt="zalo_oa_authorization_permission_confirmation_page" width="2619" height="1590" data-path="images/image-295.png" />
    </Frame>
  </Step>

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

    <Frame>
      <img src="https://mintcdn.com/chatbotx/mhgfnsJNBDee95jD/images/image-296.png?fit=max&auto=format&n=mhgfnsJNBDee95jD&q=85&s=3678b8e667a33a16d7dfb1f4e669e957" alt="chatbotx_dashboard_zalo_oa_channel_connected_status" width="2972" height="1490" data-path="images/image-296.png" />
    </Frame>
  </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 Org Settings 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>