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

# Zalo

> Connect your Zalo Official Account or Zalo bot to add AI chatbot capabilities to your customer support over Zalo chat

Transform your Zalo customer support with an intelligent AI chatbot that answers questions from your knowledge base automatically, 24/7.

## Why Connect Zalo?

<CardGroup cols={2}>
  <Card title="Instant AI Responses" icon="zap">
    Customers get immediate answers based on your website's knowledge base
  </Card>

  <Card title="24/7 Availability" icon="clock">
    AI responds day and night, even when your team is offline
  </Card>

  <Card title="Human Takeover" icon="users">
    Support agents can jump into any conversation from the dashboard
  </Card>

  <Card title="Simple Credential Setup" icon="lock">
    Connect in under a minute by pasting your OA credentials or a bot token — no OAuth or app review
  </Card>

  <Card title="Multi-Language" icon="globe">
    Vietnamese, English, and 100+ other languages, detected automatically
  </Card>

  <Card title="Knowledge-Powered" icon="brain">
    Answers based on your website's content and documentation
  </Card>
</CardGroup>

## What Can the Zalo Bot Do?

### Answer Customer Questions Instantly

Your customers can ask questions about your products, services, or content directly in a chat with your Official Account or bot:

**Example Questions:**

```text theme={null}
What are your business hours?
How do I track my order?
Tell me about your return policy
What payment methods do you accept?
```

### Provide 24/7 Support

* Responds instantly to common questions
* No waiting for business hours
* Reduces support ticket volume
* Consistent, accurate answers

### Search Your Knowledge Base

The bot uses your website's content to provide accurate answers:

* Product information
* Help articles
* FAQ sections
* Pricing details
* Shipping information

### Human Agent Handoff & Unified Inbox

Zalo chats appear in your **Live Support** unified inbox alongside website widget and other platform conversations. Each conversation shows a Zalo badge so you always know the source platform.

<Note>
  The Zalo integration responds to **1:1 chats only**. Official Account chat is always direct (no group conversations); Bot Creator bots can be in groups, but group chats are not handled by this integration. Only text messages are handled today; media (photos, stickers, voice) receive a prompt asking the customer to type their question. Proactive messaging such as ZNS (Zalo Notification Service) is not part of this integration. Personal Zalo accounts are not supported.
</Note>

**How agent replies work:**

1. Go to **Live Support** in your dashboard
2. Find the Zalo conversation (look for the Zalo badge)
3. Click to open and type your reply
4. Your message is sent directly to the customer's Zalo chat
5. The AI remains paused while you're active in the conversation

The AI resumes automatically when you leave the conversation.

## Prerequisites

Pick one of the two connection modes:

* **Official Account mode** — a **Zalo Official Account** with the chat feature enabled (configure chat mode in the Zalo OA console), plus your **OA ID**, **OA Access Token**, and **OA Secret Key** from the [Zalo developer console](https://developers.zalo.me)
* **Bot token mode** — a bot created with **Zalo Bot Creator**: in the Zalo app, search the OA **"Zalo Bot Manager"** and create a bot from its chat menu, or use [bot.zaloplatforms.com](https://bot.zaloplatforms.com). The bot token (format `123456789:abc-xyz`) arrives in a Zalo message from the bot — copy it from there

Both modes also need:

* Active BubblaV account with a website
* Website with knowledge base content (crawled pages)

## Setup Steps

<Tabs>
  <Tab title="Official Account">
    <Steps>
      <Step title="Collect your OA credentials">
        In the [Zalo developer console](https://developers.zalo.me), open your Official Account application and copy the **OA ID** and the long-lived **OA Access Token**. In the OA webhook settings, copy the **OA Secret Key** (you'll paste it both in BubblaV and in the Zalo console).
      </Step>

      <Step title="Navigate to Integrations">
        Go to **Dashboard** → **Your Website** → **Integrations** and find the Zalo card.
      </Step>

      <Step title="Click Connect">
        Click **Connect** to open the Zalo connect dialog.
      </Step>

      <Step title="Paste the credentials">
        Paste the **OA ID**, **OA Access Token**, and **OA Secret Key**, then click **Connect**. BubblaV validates the token and confirms it belongs to your OA.
      </Step>

      <Step title="Register the webhook in Zalo">
        On the Zalo configuration page, copy the **Webhook URL**. In the Zalo OA console webhook settings, paste the URL and the same **OA Secret Key**, then save. This step is manual — Zalo does not offer an API to register webhooks automatically.
      </Step>

      <Step title="Test the Bot">
        Send a chat message to your Official Account from a Zalo account to verify the AI responds correctly.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Bot token (Bot Creator)">
    <Steps>
      <Step title="Create a bot and copy its token">
        In the Zalo app, search the OA **"Zalo Bot Manager"** and use **Bot Creator** from its chat menu (or create the bot at [bot.zaloplatforms.com](https://bot.zaloplatforms.com)). Copy the bot token (format `123456789:abc-xyz`) from the Zalo message the bot sends you.
      </Step>

      <Step title="Navigate to Integrations">
        Go to **Dashboard** → **Your Website** → **Integrations** and find the Zalo card.
      </Step>

      <Step title="Choose Bot token and paste it">
        Click **Connect**, choose **Bot token**, paste the token, and click **Connect**. BubblaV validates it and registers the webhook automatically — no manual setup.
      </Step>

      <Step title="Test the Bot">
        Send a chat message to your bot from a Zalo account to verify the AI responds correctly.
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Managing Your Integration

### View Connected Account

From the Zalo configuration page, you can see:

* Account name (OA name or bot account name) and connection status
* The **Webhook URL** (for Official Accounts: to register in the Zalo OA console, with a copy button; for bot-token connections: registered automatically)
* Technical details (admin debug view)

<Note>
  Bots connected with a bot token have their webhook registered and removed automatically by BubblaV (at connect, resume, pause and disconnect) — no manual steps.
</Note>

### Disconnect Your Account

To remove the Zalo integration:

1. Go to **Dashboard** → **Your Website** → **Integrations**
2. Find the Zalo card and disconnect it

**Note:** Disconnecting stops the AI from responding to messages on that account. For Official Accounts, since webhook registration is manual, also remove the webhook URL in the Zalo OA console so Zalo stops delivering events. For bot-token connections the webhook is deregistered automatically.

## How Messages Are Processed

1. **Customer sends a chat** → Message arrives at your Zalo Official Account or bot
2. **Webhook triggers** → BubblaV receives the event (Official Accounts: authenticated by the `?t=` token in the webhook URL and verified by the payload MAC signature; bots: verified by the per-bot secret token header)
3. **AI analyzes question** → Your website's knowledge base is searched
4. **Response generated** → AI formulates an answer with sources
5. **Sent to Zalo** → Customer receives the response
6. **Conversation logged** → Message stored in your dashboard

## Zalo Messaging Notes

* **Session-based messaging (Official Accounts)**: Official Account chats are session-based — the OA replies within a chat session window that opens when the customer messages you. In practice this covers normal support conversations — the customer writes first, the bot replies. Bot-token connections are not session-limited.
* **Chat feature required (Official Accounts)**: Your OA must have the chat feature enabled in the Zalo OA console for customers to message it.
* **Messages are truncated** at 2000 characters (both modes).
* **One account per website**: A single Official Account or bot can only be connected to one website at a time.

## Troubleshooting

### Messages Not Being Received

1. Confirm the **Webhook URL** is pasted in the Zalo OA console exactly as shown on the configuration page — including the `?t=` token (Official Accounts; bot-token connections register automatically — if a bot stops receiving, reconnect it)
2. Confirm the **OA Secret Key** in the Zalo console matches the one you entered in BubblaV (a mismatch fails MAC verification)
3. Check that your OA has the **chat feature enabled** in the Zalo OA console
4. Confirm the integration is **active** in your dashboard

### Bot Not Responding

1. Verify the integration is active in the dashboard
2. Check your website has crawled content in the Knowledge section
3. Test with a simple question like "What are your hours?"
4. Reconnect with a fresh access token if the old one was revoked in the Zalo developer console

### Invalid Token Error

1. Make sure you copied the **full access token** from the Zalo developer console (or, for bots, the **full bot token** — it looks like `123456789:abc-xyz` — from the Zalo Bot Creator message)
2. Confirm the **OA ID** matches the OA the token belongs to — BubblaV rejects a token/OA ID mismatch
3. Generate a new token in the Zalo developer console if the old one expired, then reconnect

## FAQ

<AccordionGroup>
  <Accordion title="Do I need a developer to set it up?">
    No. For an Official Account, copy your OA ID, OA Access Token, and OA Secret Key from the Zalo developer console, paste them into the BubblaV dashboard, then paste the webhook URL we give you into the Zalo OA console. For a bot, just paste the single bot token — the webhook is registered automatically. No code or OAuth required.
  </Accordion>

  <Accordion title="Does the bot reply in group chats?">
    No. Zalo Official Account chat is always 1:1 between the customer and your business — the bot answers those direct chats. Bot Creator bots can be added to groups, but group chats are not handled by this integration.
  </Accordion>

  <Accordion title="Why do I have to paste the webhook URL into the Zalo console?">
    Zalo does not offer an API for registering Official Account webhooks, so that final step is manual. It takes a few seconds: copy the Webhook URL from the BubblaV Zalo configuration page and paste it into your OA webhook settings in the Zalo OA console. Bot-token connections don't need this — their webhook is registered automatically.
  </Accordion>

  <Accordion title="Can I connect the same account to multiple websites?">
    No. A Zalo Official Account or bot can only be connected to one website at a time. Connect a separate account for each website.
  </Accordion>

  <Accordion title="Can I connect my personal Zalo account?">
    No. Automating a personal Zalo account requires unofficial tools that violate Zalo's terms and can get the account banned. Use an Official Account or a Bot Creator bot instead.
  </Accordion>

  <Accordion title="What happens when the AI can't answer?">
    If the AI is unsure or the customer needs complex help, the conversation can be escalated to a human agent. You'll see all conversations in the Live Support dashboard and can jump in anytime.
  </Accordion>

  <Accordion title="What languages does the bot support?">
    The AI supports 100+ languages, including Vietnamese, and can automatically detect the language being used to respond appropriately.
  </Accordion>
</AccordionGroup>

## Next Steps

* Set up your [Live Support](/user-guide/live-support) to monitor conversations
* Improve your [Knowledge Base](/user-guide/knowledge) content for better answers
* Explore other [Integrations](/user-guide/integrations/overview) to connect more platforms