Zalo (Official Account)

Status: experimental. DMs via Zalo Official Account (OA) webhooks are supported.

ClawCentral connects to Zalo via the Zalo Official Account (OA) webhook API. Zalo POSTs events to ClawCentral's managed platform; ClawCentral verifies the HMAC-SHA256 mac header on every inbound request automatically. No local server or tunnel is needed.

Webhook URL

https://<your-tenant>.clawcentral.io/webhooks/zalo

Replace <your-tenant> with your ClawCentral tenant slug.

Required credentials

Set these in Admin UI → Settings → Tenant Settings → Secrets:

Secret	Description
ZALO_APP_ID	Your Zalo application ID
ZALO_OA_SECRET_KEY	OA secret key used to verify the HMAC-SHA256 mac header on inbound webhooks
ZALO_OA_ACCESS_TOKEN	OA access token used to send messages via the Zalo API

What it is

Zalo is a Vietnam-focused messaging app. The Official Account (OA) API lets ClawCentral receive and send messages on behalf of your Zalo OA. It is a good fit for support or notifications where you want deterministic routing back to Zalo.

• Deterministic routing: replies always go back to the same Zalo chat.
• DMs share the user's main session.
• ClawCentral verifies HMAC-SHA256 signatures on all inbound webhook requests.

Setup

Step 1: Create a Zalo Official Account and App

1. Go to Zalo Developer Portal and sign in.
2. Create or select a Zalo Official Account.
3. In the developer portal, create an application linked to your OA.
4. Copy the App ID and OA Secret Key.
5. Obtain the OA Access Token (from the OA management console or via the OAuth flow).

Step 2: Configure the webhook URL in Zalo

In the Zalo developer portal or OA management console:

1. Set the webhook URL to:

   https://<your-tenant>.clawcentral.io/webhooks/zalo

2. Enable the event types you need (at minimum: message events).

Step 3: Enter credentials in Admin UI

1. Open your Admin UI at https://<your-tenant>.clawcentral.io/
2. Go to Settings → Tenant Settings → Secrets
3. Add ZALO_APP_ID, ZALO_OA_SECRET_KEY, and ZALO_OA_ACCESS_TOKEN as key-value pairs
4. Save each secret

How it works

• Inbound messages are verified using HMAC-SHA256 on the mac header with the OA secret key.
• Messages are normalized into ClawCentral's standard channel envelope.
• Replies always route back to the same Zalo chat.
• Duplicate events (matched by event type + message ID) are ignored within a short replay window.

Limits

• Outbound text is chunked to 2000 characters (Zalo API limit).
• Streaming responses are suppressed due to the 2000 character limit making streaming less useful.
• Media uploads/downloads are capped by the platform's configured media size limit.

Access control (DMs)

• Default: unknown senders receive a pairing code; messages are ignored until approved.
• Approve senders via the Admin UI.
• Allowlists accept numeric Zalo user IDs.

Access control (Groups)

Group support depends on the specific Zalo OA product surface. For many OA configurations, bots cannot be added to group conversations. If group messages arrive, they are blocked by default unless explicitly allowed in Admin UI settings.

Group policy values:

• Disabled (default) — blocks all group messages.
• Open — allows any group member (mention-gated).
• Allowlist — only allowed sender IDs are accepted.

Supported message types

• Text messages: Full support with 2000 character chunking.
• Plain URLs in text: Treated as normal text input.
• Link previews / rich link cards: May not reliably trigger a reply (Zalo OA behavior varies).
• Image messages: Support varies by OA configuration; verify in your environment.
• Stickers, voice notes, audio, video, file attachments: Limited — ClawCentral may not generate a reply for these types depending on your OA permissions.
• Unsupported types: Logged.

Capabilities

Feature	Status
Direct messages	Supported
Groups	Limited — depends on OA product surface
Media (inbound images)	Limited / verify in your environment
Media (outbound images)	Limited / verify in your environment
Plain URLs in text	Supported
Link previews	Unreliable
Reactions	Not supported
Stickers	No reply generated
Voice notes / audio / video	No reply generated
File attachments	No reply generated
Threads	Not supported
Polls	Not supported
Streaming	Suppressed (2000 char limit)

Troubleshooting

Bot doesn't respond:

• Verify ZALO_APP_ID, ZALO_OA_SECRET_KEY, and ZALO_OA_ACCESS_TOKEN are correctly entered in Admin UI → Settings → Tenant Settings → Secrets.
• Confirm the sender is approved (pairing or allowlist).
• Check that the webhook URL configured in the Zalo portal is exactly https://<your-tenant>.clawcentral.io/webhooks/zalo.

Webhook not receiving events:

• Confirm the webhook URL is saved in the Zalo developer portal or OA management console.
• Verify the correct event types are enabled in the Zalo portal.
• Confirm ZALO_OA_SECRET_KEY matches the secret configured in the Zalo portal (HMAC verification will fail if they differ).

Related

• Channel troubleshooting
• Security