> ## Documentation Index
> Fetch the complete documentation index at: https://docs-eos.fpt.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Zalo channel

> Connect an Official Account so the Digital Worker answers customer messages on Zalo automatically

The Zalo channel links an Official Account to the Digital Worker. Once connected, every message a customer sends to the Official Account is answered by the Digital Worker automatically.

> [!NOTE]
>
> The configuration panel opens from the **Channels** tab - click the **Zalo** channel. The panel is titled "Zalo configuration".

![Zalo configuration panel](https://mintcdn.com/fpt-15dbd015/gDW0AWl75k3m2kQW/images/eos/en_zl_config.jpg?fit=max\&auto=format\&n=gDW0AWl75k3m2kQW\&q=85\&s=3d0bca55dbacbd6616d60c790758b75b)

## Before you connect

You need admin rights on the Zalo Official Account and its matching Zalo application, plus three secrets:

| Secret | Where to get it |
| - | - |
| **OA Secret Key** | The Official Account's Webhook section |
| **App Secret** | The Zalo application settings, not the OA admin page |
| **Refresh Token** | The application's OAuth authorisation flow |

> [!WARNING]
>
> Get any one of these three wrong and the connection fails, with every incoming message rejected. Copy them exactly, with no leading or trailing spaces.

## Declaring the webhook on Zalo

The **Webhook URL** box at the top of the panel is read-only, with a copy button:

```text theme={null}
https://console-agents.fpt.ai/webhooks/zalo
```

**1. Copy the Webhook URL**

Click the copy button beside the box.

**2. Paste it into your Zalo application**

Open your Zalo application and paste it into the Webhook field.

**3. Save it on Zalo**

Save the webhook settings before returning to Console.

> [!NOTE]
>
> One webhook address serves every Official Account. The system tells accounts apart by the OA ID inside the data Zalo sends, so you do not need a separate address per OA.

## The fields

| Field | Required | Description |
| - | - | - |
| **Webhook URL** | Read-only | The address that receives data from Zalo; copy it into the Zalo application |
| **App ID** | Yes | The Zalo application identifier. Not a secret, but it is what incoming messages are authenticated against |
| **App Secret** | Yes | From the Zalo application settings, not the OA admin page. Shown masked |
| **OA Secret Key** | Yes | The Official Account's secret key, used to authenticate the webhook. Shown masked |
| **Refresh Token** | Yes | From the OAuth flow. Zalo issues a new token after each use and the system always keeps the latest. Shown masked |
| **Display name** | No | The channel's display name. Leave it empty and the system uses the Official Account name Zalo returns |

## Connecting the Official Account

**1. Open the Zalo channel**

Go to the **Channels** tab and click the **Zalo** channel, which starts as Not configured.

**2. Declare the webhook on Zalo**

Copy the Webhook URL and paste it into the Zalo application as described above.

**3. Enter App ID, App Secret, OA Secret Key and Refresh Token**

Paste each value exactly into its matching box.

**4. Set a display name if you want one**

Enter a **Display name**, or leave it empty to use the Official Account name.

**5. Click Connect**

The system checks the details with Zalo. On success the channel moves out of Not configured.

## Editing the connection

Reopen the Zalo channel from the Channels tab. Secret fields are masked; type a new value to replace one, or leave it alone to keep it. Click **Connect** to save, or **Cancel** to close without saving.

> [!TIP]
>
> Zalo issues a fresh Refresh Token after each use. If the channel suddenly stops answering, get a new Refresh Token from the OAuth flow and update it here.

## Disconnecting

There are two ways to stop serving on Zalo:

> **Switch it off at publish time**
>
> Open the **Publish** dialog, untick **Zalo** under External channels and publish. The connection details are kept.

> **Disconnect it entirely**
>
> Open the Zalo configuration panel and disconnect. The secrets are wiped, so you would have to enter them again to come back.

> [!WARNING]
>
> Once disconnected, customers writing to the Official Account no longer get an answer from the Digital Worker. Have a plan for handling messages manually before you disconnect.

## Common problems

| Symptom | Usual cause | What to do |
| - | - | - |
| Connect returns an error | Wrong App Secret, OA Secret Key or Refresh Token | Fetch the correct values from Zalo and paste them again |
| Connected, but no messages arrive | The Webhook URL was never declared in the Zalo application | Copy the Webhook URL again and save it on Zalo |
| Customers see "This conversation is unavailable" | The Digital Worker is not published, or Zalo was not ticked at publish time | See [Publishing](https://docs-eos.fpt.ai/eos/en/publishing.md) |
| A running channel suddenly stops answering | The Refresh Token has expired | Update it with a new Refresh Token |

> [!NOTE]
>
> See the overall state of every channel and switch the serving version on [Managing deployment channels](https://docs-eos.fpt.ai/eos/en/manage-channels.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.