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

# Configure Zalo Official Account

> Learn how to register a Zalo Developer application, verify your domain, configure webhooks, and set up Zalo OA credentials on your portal.

Integrating the Zalo Official Account (Zalo OA) portal connection allows your customers to manage conversations, track follows, and automate responses on Zalo right from the unified customer support inbox.

## Prerequisites

Before you begin, make sure you have:

* Super Admin access to your portal to input credentials.
* 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 your portal.

<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 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 the Admin Portal

A Super Admin must enter the Zalo credentials in the Admin Portal before the integration can work.

<Steps>
  <Step title="Open Integrations">
    Log in to your Admin Portal, navigate to:

    ```text theme={null}
    https://app.chatconnectx.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, the system will display the **Auth Callback URL** and **Webhook URL**. Copy 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 your portal is hosted.

<Steps>
  <Step title="Get the verification URL from the system">
    Copy the domain of your portal where the application is hosted:

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

  <Step title="Complete domain verification in Zalo">
    Go to your Zalo application settings and follow the Zalo domain verification guide. Add the meta tag obtained from Zalo to your portal 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

You need to configure two URLs in your Zalo application to receive messages and events on the portal.

<Steps>
  <Step title="Set the Callback URL in Zalo">
    Copy the **Auth Callback URL** from the Admin Portal Zalo configuration 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 the Admin Portal Zalo configuration 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>

## User Connection Guide

After completing the app configuration on Zalo Developers and entering the Credentials in the Admin Portal, your customers can connect their Zalo OA.

For step-by-step instructions, see the [Zalo OA Connection Guide](/channels/zalo/connect-zalo-oa).

## Troubleshooting

<AccordionGroup>
  <Accordion title="Messages not appearing in portal">
    * 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 the portal and Zalo
  </Accordion>

  <Accordion title="Domain verification failing">
    * Ensure your portal 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** match the App ID and Secret Key in Zalo
  </Accordion>

  <Accordion title="How do I get help if the issue persists?">
    1. Check the 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>