Connect Zalo OA to the ChatHub inbox

What this guide covers#

The ChatHub Zalo OA channel receives messages customers send to a Zalo Official Account and lets staff reply from the shared inbox — with the images, files and locations customers share. It runs on Zalo's official Open API, unlike the personal Zalo channel (QR sign-in): an OA is a business account, stable and within Zalo's terms.

Configuration has two sides. On Zalo for Developers you prepare an application, have your OA grant that application access, then collect three values: the App ID, the Secret Key and a refresh token. In ChatHub you paste those three in, copy the Webhook URL ChatHub provides over to Zalo, then click Connect. The whole thing takes about fifteen minutes.

To receive messages over the webhook, the ChatHub installation must have a public HTTPS domain reachable from the Internet. Zalo only delivers events to an HTTPS address, so a server behind NAT or with only an internal address will not receive messages until it has a public domain.

1. Before you start#

1. 1

   An approved Zalo Official Account for which you are an administrator (so you can grant an application access).

2. 2

   A Zalo account to sign in to Zalo for Developers at developers.zalo.me.

3. 3

   A ChatHub installation with a public HTTPS domain (for example https://chat.company.com). If you do not have one yet, set up the domain before the webhook step.

4. 4

   Administrator rights in ChatHub so you can open Channels and add an account.

2. Prepare the app and grant OA access (on Zalo for Developers)#

This step happens entirely on Zalo for Developers. The goal is to have an application and to have your Official Account grant that application management access — the prerequisite for getting a refresh token in the next step.

1. 1

   Open developers.zalo.me and sign in with your Zalo account.

2. 2

   Create a new application and give it a memorable name.

3. 3

   In the application, add the Official Account product and link your OA: select the OA and grant the application access to manage it. The OA administrator must confirm this grant.

4. 4

   Verify the application's domain: register your ChatHub installation's domain (the public HTTPS one) in the application's domain section, following Zalo's verification steps. Without this, Zalo may refuse to deliver webhooks to your address.

3. Get the App ID, Secret Key and refresh token#

ChatHub needs exactly three values. The App ID and Secret Key belong to the application; the refresh token represents the access the OA just granted the application.

1. 1

   App ID and Secret Key: open the application's info page on Zalo for Developers. The App ID shows in the general info; the Secret Key is in the application's secret-key section. Copy both.

2. 2

   Refresh token: after the OA grants the application access, Zalo issues an authorization code; exchange it for an access token + refresh token pair through Zalo's OAuth v4 flow (or use Zalo's helper tool for obtaining OA tokens). What ChatHub needs is the refresh token.

3. 3

   Keep these three values to paste into ChatHub in step 5. Do not send them over chat or email.

4. Add the Zalo OA channel in ChatHub#

1. 1

   In ChatHub, go to Administration -> Channels and click Add account in the top right.

2. 2

   In the channel type column of the dialog, choose Zalo OA (Official Account).

3. 3

   Give the channel a memorable name, for example Store Zalo OA — this name only appears inside ChatHub to tell channels of the same type apart.

4. 4

   Paste the App ID into the App ID field, the Secret Key into the Secret Key field, and the refresh token into the Refresh token field. The Access token field is optional — leave it empty and ChatHub obtains an access token from the refresh token on connect.

1. 1

   Scroll to the bottom of the form to the Webhook URL for the Zalo app block. Click Copy to grab the webhook address — it looks like https://<your-domain>/api/channels/webhooks/zalo-oa and is shared by every OA channel of the installation.

2. 2

   In Zalo for Developers, open the application under Official Account -> Webhook, paste the copied address into the Webhook URL field and save. Make sure the application's domain is verified (step 2).

3. 3

   Back in ChatHub, click Create account. The channel dialog opens with the status Disconnected.

5. Connect and test#

1. 1

   In the channel dialog you just opened, click Connect. ChatHub calls Zalo to verify the credentials and read the OA identity.

2. 2

   After a few seconds the status turns from Disconnected to Active, and the channel name and avatar are replaced by the OA's own name and picture.

3. 3

   From a phone, send a test message to the OA. Open Messages in ChatHub: the new conversation appears with a Zalo badge. Reply from ChatHub and check the message reaches the right customer on Zalo.

When something goes wrong, ChatHub writes the cause on the channel instead of a raw Zalo code:

1. 1

   Zalo refused to refresh the access token — the refresh token expired or was used elsewhere (for example someone re-fetched the token on Zalo for Developers). Grant the application access again to get a new refresh token, then re-enter the credentials per step 7.

2. 2

   Missing App ID, Secret Key or refresh token — go back to step 4 and fill in all three.

3. 3

   The webhook receives nothing — check that the Webhook URL was pasted correctly on Zalo, the application's domain is verified, and the installation's APP_URL is a public HTTPS address.

6. Re-enter the credentials when needed#

A Zalo refresh token is single-use and cannot be re-requested through the API. If the refresh chain breaks — a lost token rotation, or you rotated the Secret Key on Zalo — replace the keys in place, without deleting the channel (deleting it would take all of the OA's conversations with it).

1. 1

   Open the Zalo OA channel in Channels and scroll to the App credentials section.

2. 2

   Re-enter the App ID, Secret Key and a new refresh token (the Access token can stay empty), then click Save credentials.

3. 3

   The channel returns to Disconnected. Click Connect to verify the new keys. Existing conversations and messages are kept.

7. Scope and limits worth knowing#

1. 1

   One-to-one only: an OA talks privately with each follower; there are no group messages.

2. 2

   Images: up to 1 MB each (JPG/PNG). Larger images are rejected by Zalo; ChatHub tells you to resize or send them as a file.

3. 3

   Files: up to 5 MB each. Send larger files as a download link.

4. 4

   Video cannot be sent through the Zalo OA messaging API; ChatHub blocks it early and suggests sending an image, a file, or a link to the video.

5. 5

   History cannot be pulled: Zalo OA has no history API, so the channel only receives messages from the moment it connects onward.

6. 6

   There are no read receipts for an OA, so the inbox does not show whether a customer has seen a message.

7. 7

   Security signature: every event Zalo sends is verified by ChatHub against the X-ZEvent-Signature using the application's Secret Key, so no one can forge a message into the inbox.

See also: the channel types ChatHub supports ↗