Skip to main content
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.
  • A valid Vietnamese mobile phone number.
Zalo OA is a popular messaging channel in Vietnam. A Vietnamese mobile phone number is required to register on the Zalo Developer platform.

​
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.
1

Register on Zalo Developers

Go to Zalo Developers and sign in with your Zalo account. If you don’t have a developer account, register one using your Vietnamese phone number.
zalo_developers_portal_homepage_login
2

Create a new application

Follow the official Zalo documentation to create a new application. Provide your application name and description.
zalo_developers_create_new_application_form
3

Activate the application

After the application is created, set its status to Active in the application dashboard.
zalo_developers_application_status_active
4

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.
zalo_app_dashboard_app_id_secret_key
5

Enable required APIs

Navigate to the API settings in your Zalo application and enable the required APIs.
zalo_app_api_settings_enabled_apis_list

​
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.
1

Open Integrations

Log in to your Admin Portal, navigate to:
https://app.chatconnectx.com/manage/integrations
Then find the Zalo card.
2

Open the Zalo configuration

Click the Edit button on the Zalo card to open the configuration modal.
chatbotx_edit_zalo_modal
3

Fill in the Zalo credentials

In the Edit Zalo modal, fill in the following fields:
FieldDescriptionWhere to find
Client IDZalo Application IDZalo Developers → App Dashboard
Client SecretZalo Application’s Private KeyZalo Developers → App Dashboard
API VersionAPI version to usee.g., v1.0
Webhook Verify TokenAny string you create yourselfSelf-generated
The Webhook Verify Token is a unique string you generate yourself. Zalo uses this token to verify webhook requests from your server.
fill-in-the-zalo-credentials
4

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

​
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.
1

Get the verification URL from the system

Copy the domain of your portal where the application is hosted:
app.chatconnectx.com
2

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.
zalo_developers_domain_verification_meta_tag_setup
3

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

​
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.
1

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.
zalo_app_settings_callback_url_permissions_configuration
2

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:
send_msg
get_msg
follow
unfollow
zalo_app_webhook_url_event_subscriptions

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

​
Troubleshooting

  • 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
  • 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)
  • 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
  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