Zalo
=====

Connects an agent to a Zalo Official Account. Users message the account on Zalo; the agent receives and replies within the same conversation.

* **Supported agents:** Chatbot
* **Route type:** Conversation

Before You Start
----------------

1. Create an account at the **Zalo Developer Portal** (`developers.zalo.me <https://developers.zalo.me>`_).
2. Create a **Zalo App** and link it to your **Official Account**.
3. In your app's **Application Management → Webhook** section, note the **App ID**, **App Secret**, **Official Account ID**, and **OA Secret Key**.
4. Register the redirect URL in the Zalo Developer Portal. The format is ``<viewer-base-url>/api/v1/zalo/callback``. If using an API gateway, enter its proxy URL instead.

Your agent must be published with an active version. The Channel Gateway MCP must also be enabled:

* **Global:** Admin Panel → MCP Servers → Channel Gateway → Enable and Deploy
* **Workspace:** Workspace Settings → MCP → Channel Gateway → toggle ON

Configuration
-------------

**Credentials**

* **App ID** — The App ID from the Zalo Developer Portal. Required.
* **App Secret** — The App Secret from the Zalo Developer Portal. Required.
* **Official Account ID** — The ID of the linked Zalo Official Account. Required.
* **OA Secret Key** — Found in Application Management → Webhook in the Zalo portal. Used to validate incoming webhook signatures. Required.
* **Redirect URL** — The OAuth callback URL. Leave blank to use the default platform URL. Optional.

**Route Settings**

* **Description** — Optional label for this channel instance.
* **Purpose** — Optional note on when the agent should use this channel.
* **Session Expiry (hours)** — Idle timeout before a conversation session resets. Default: 4. Range: 0.01–48.