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

# Cấu hình Zalo Official Account

> Hướng dẫn tạo ứng dụng Zalo Developer, cấu hình tên miền xác thực, webhook và Credentials kết nối Zalo OA trên portal của bạn.

Tích hợp cổng kết nối Zalo Official Account (Zalo OA) lên portal giúp khách hàng của bạn có thể quản lý tin nhắn, tiếp nhận quan tâm và tự động phản hồi khách hàng qua Zalo OA ngay trên giao diện CSKH tập trung.

## Điều kiện chuẩn bị

Trước khi bắt đầu, hãy đảm bảo bạn có:

* Quyền quản trị cao nhất (Super Admin) trên Portal của bạn để nhập cấu hình.
* Một tài khoản Zalo OA (Official Account) đã đăng ký với quyền quản trị viên.
* Một tài khoản nhà phát triển đăng ký tại cổng [Zalo Developers](https://developers.zalo.me/).
* Một số điện thoại di động Việt Nam đang hoạt động ổn định để đăng ký và nhận xác thực.

<Note>
  Zalo OA là kênh tương tác phổ biến tại Việt Nam. Bạn bắt buộc phải có số điện thoại Việt Nam để hoàn tất đăng ký tài khoản trên nền tảng nhà phát triển của Zalo.
</Note>

## Bước 1: Tạo ứng dụng Zalo (Zalo Application)

Nếu chưa có ứng dụng Zalo, bạn thực hiện tạo mới ứng dụng trên cổng Zalo Developer trước khi liên kết với hệ thống của mình.

<Steps>
  <Step title="Đăng ký tài khoản trên Zalo Developers">
    Truy cập [Zalo Developers](https://developers.zalo.me/) và đăng nhập bằng tài khoản Zalo của bạn. Nếu chưa có tài khoản nhà phát triển, tiến hành đăng ký bằng số điện thoại di động Việt Nam.

    <Frame>
      <img src="https://mintcdn.com/chatbotx/ILDlPWyJuzzPj7RT/images/image-282.png?fit=max&auto=format&n=ILDlPWyJuzzPj7RT&q=85&s=68f805c84557626575c9d9fa8d39b3b2" alt="zalo_developers_portal_homepage_login" width="2994" height="1588" data-path="images/image-282.png" />
    </Frame>
  </Step>

  <Step title="Tạo ứng dụng mới">
    Làm theo tài liệu hướng dẫn chính thức từ Zalo hoặc đi đến mục tạo ứng dụng, điền tên ứng dụng hiển thị và mô tả ngắn gọn về sản phẩm của bạn.

    <Frame>
      <img src="https://mintcdn.com/chatbotx/ILDlPWyJuzzPj7RT/images/image-283.png?fit=max&auto=format&n=ILDlPWyJuzzPj7RT&q=85&s=dce36c89f323506b892f88f884976846" alt="zalo_developers_create_new_application_form" width="3004" height="1476" data-path="images/image-283.png" />
    </Frame>
  </Step>

  <Step title="Kích hoạt trạng thái hoạt động">
    Sau khi ứng dụng được tạo, hãy chuyển trạng thái của ứng dụng sang **Active** (Hoạt động) trong giao diện Dashboard của ứng dụng.

    <Frame>
      <img src="https://mintcdn.com/chatbotx/ILDlPWyJuzzPj7RT/images/image-284.png?fit=max&auto=format&n=ILDlPWyJuzzPj7RT&q=85&s=c7dae0789f9110de017c42111f9c6632" alt="zalo_developers_application_status_active" width="3010" height="1530" data-path="images/image-284.png" />
    </Frame>
  </Step>

  <Step title="Sao chép App ID và Secret Key">
    Trong giao diện Dashboard của ứng dụng Zalo, sao chép mã **Application ID** (App ID) và **Application's Private Key** (Secret Key). Bạn sẽ cần hai thông số này ở bước sau.

    <Frame>
      <img src="https://mintcdn.com/chatbotx/ILDlPWyJuzzPj7RT/images/image-285.png?fit=max&auto=format&n=ILDlPWyJuzzPj7RT&q=85&s=5e68f2baa5af270f79e178c88f2adde5" alt="zalo_app_dashboard_app_id_secret_key" width="3010" height="1530" data-path="images/image-285.png" />
    </Frame>
  </Step>

  <Step title="Kích hoạt các API cần thiết">
    Truy cập vào mục cấu hình API trong ứng dụng Zalo của bạn và kích hoạt đầy đủ các API liên quan đến gửi/nhận tin nhắn và quản lý tài khoản Zalo OA.

    <Frame>
      <img src="https://mintcdn.com/chatbotx/ILDlPWyJuzzPj7RT/images/image-286.png?fit=max&auto=format&n=ILDlPWyJuzzPj7RT&q=85&s=fcb64b1a1a16e49037e8bbf8fb31ad30" alt="zalo_app_api_settings_enabled_apis_list" width="2925" height="1841" data-path="images/image-286.png" />
    </Frame>
  </Step>
</Steps>

## Bước 2: Cấu hình Credentials trên Portal quản trị

Bạn cần nhập thông tin ứng dụng Zalo vào Portal quản trị dưới tư cách Super Admin trước khi có thể kết nối Zalo OA cho khách hàng.

<Steps>
  <Step title="Mở trang cấu hình kết nối">
    Đăng nhập vào Portal quản trị của bạn, truy cập mục:

    ```text theme={null}
    https://app.chatconnectx.com/manage/integrations
    ```

    Sau đó tìm thẻ cấu hình **Zalo**.
  </Step>

  <Step title="Mở cấu hình Zalo">
    Nhấn nút **Edit** trên thẻ Zalo để hiển thị biểu mẫu điền thông tin.

    <Frame>
      <img src="https://mintcdn.com/chatbotx/ILDlPWyJuzzPj7RT/images/image-287.png?fit=max&auto=format&n=ILDlPWyJuzzPj7RT&q=85&s=259b9521d72295379e01aaec171f369a" alt="chatbotx_edit_zalo_modal" width="2300" height="1548" data-path="images/image-287.png" />
    </Frame>
  </Step>

  <Step title="Nhập thông tin Credentials">
    Tại cửa sổ **Edit Zalo**, nhập đầy đủ thông tin vào các trường sau:

    | Trường                   | Mô tả                                | Nơi lấy thông tin                    |
    | ------------------------ | ------------------------------------ | ------------------------------------ |
    | **Client ID**            | Mã ID ứng dụng Zalo                  | Zalo Developers → Dashboard ứng dụng |
    | **Client Secret**        | Khóa bảo mật ứng dụng                | Zalo Developers → Dashboard ứng dụng |
    | **API Version**          | Phiên bản API sử dụng                | Ví dụ: `v1.0`                        |
    | **Webhook Verify Token** | Chuỗi ký tự bảo mật xác thực webhook | Bạn tự tạo một chuỗi ngẫu nhiên      |

    <Note>
      Mã **Webhook Verify Token** là chuỗi bảo mật do bạn tự quy định. Zalo sẽ gửi kèm mã này trong yêu cầu gửi về để hệ thống của bạn đối chiếu nhằm xác minh nguồn yêu cầu thực sự từ Zalo.
    </Note>

    <Frame>
      <img src="https://mintcdn.com/chatbotx/ILDlPWyJuzzPj7RT/images/image-288.png?fit=max&auto=format&n=ILDlPWyJuzzPj7RT&q=85&s=b892d5d5ef42cc362da6252439037e70" alt="fill-in-the-zalo-credentials" width="2291" height="1512" data-path="images/image-288.png" />
    </Frame>
  </Step>

  <Step title="Lưu cấu hình">
    Nhấn **Save** để lưu lại. Thẻ Zalo lúc này sẽ hiển thị mã Client ID.

    Sau khi lưu thành công, hệ thống hiển thị hai đường dẫn **Auth Callback URL** và **Webhook URL**. Hãy sao chép cả hai đường dẫn này để cấu hình ở các bước tiếp theo.

    <Frame>
      <img src="https://mintcdn.com/chatbotx/w6VS-GzWGWlJyR_i/images/image-307.png?fit=max&auto=format&n=w6VS-GzWGWlJyR_i&q=85&s=fe387d8e5851251b53a8c630e14686a1" alt="Image" width="1170" height="808" data-path="images/image-307.png" />
    </Frame>
  </Step>
</Steps>

## Bước 3: Xác thực tên miền (Domain Verification)

Zalo yêu cầu xác thực sở hữu tên miền trước khi ứng dụng của bạn có thể tiếp nhận sự kiện webhook. Bước này đảm bảo bạn thực sự làm chủ tên miền nơi portal được cài đặt.

<Steps>
  <Step title="Lấy tên miền portal từ hệ thống">
    Sao chép chính xác địa chỉ tên miền portal quản trị của bạn:

    ```text theme={null}
    app.chatconnectx.com
    ```
  </Step>

  <Step title="Cấu hình xác thực tên miền trên Zalo">
    Đi đến phần thiết lập trên Zalo Developer và làm theo hướng dẫn xác thực tên miền của Zalo. Dán mã thẻ Meta tag do Zalo cung cấp vào phần HTML của website hoặc cấu hình bản ghi DNS tương ứng.

    <Frame>
      <img src="https://mintcdn.com/chatbotx/tyPKYprKEiHEDyz2/images/image-308.png?fit=max&auto=format&n=tyPKYprKEiHEDyz2&q=85&s=4a109748b60ee5ae9e293b5cf8f60fa7" alt="zalo_developers_domain_verification_meta_tag_setup" width="3808" height="1814" data-path="images/image-308.png" />
    </Frame>
  </Step>

  <Step title="Xác nhận trạng thái xác thực">
    Trạng thái cập nhật tên miền có thể mất vài giây. Nhấn kiểm tra lại trạng thái xác thực trong Dashboard ứng dụng của Zalo sau khoảng 3-5 giây. Bạn có thể cần nhấn kiểm tra lại 2-3 lần để trạng thái được cập nhật mới.

    <Frame>
      <img src="https://mintcdn.com/chatbotx/tyPKYprKEiHEDyz2/images/image-309.png?fit=max&auto=format&n=tyPKYprKEiHEDyz2&q=85&s=8360a1ee1dc3f63aba61992cfddcfc44" alt="zalo_developers_domain_verification_status_confirmed" width="3530" height="1688" data-path="images/image-309.png" />
    </Frame>
  </Step>
</Steps>

## Bước 4: Thiết lập Callback URL và Webhook URL trên ứng dụng Zalo

Bạn cấu hình hai đường dẫn liên kết Zalo đã lấy từ Bước 2 vào ứng dụng Zalo để kích hoạt luồng nhận tin nhắn và sự kiện.

<Steps>
  <Step title="Nhập Callback URL trên Zalo">
    Sao chép đường dẫn **Auth Callback URL** từ trang cấu hình Portal quản trị của bạn, dán vào ô Callback URL trong phần cài đặt ứng dụng Zalo và tích chọn đầy đủ các quyền yêu cầu cho OAuth.

    <Frame>
      <img src="https://mintcdn.com/chatbotx/gwEdLyxU_QvH0ENX/images/image-292.png?fit=max&auto=format&n=gwEdLyxU_QvH0ENX&q=85&s=d70db9af54f71626256f4caf131b4dbf" alt="zalo_app_settings_callback_url_permissions_configuration" width="3000" height="1600" data-path="images/image-292.png" />
    </Frame>
  </Step>

  <Step title="Nhập Webhook URL trên Zalo">
    Sao chép đường dẫn **Webhook URL** từ trang cấu hình Portal quản trị, dán vào ô Webhook URL trong ứng dụng Zalo. Tích chọn đăng ký nhận các sự kiện sau:

    ```text theme={null}
    send_msg
    get_msg
    follow
    unfollow
    ```

    <Frame>
      <img src="https://mintcdn.com/chatbotx/gwEdLyxU_QvH0ENX/images/image-293.png?fit=max&auto=format&n=gwEdLyxU_QvH0ENX&q=85&s=2c1d05952fd5fe2399845fe7d4265237" alt="zalo_app_webhook_url_event_subscriptions" width="3014" height="1422" data-path="images/image-293.png" />
    </Frame>
  </Step>
</Steps>

## Hướng dẫn kết nối cho người dùng

Sau khi hoàn tất cấu hình ứng dụng trên Zalo Developers và nhập Credentials vào Portal quản trị, khách hàng của bạn có thể tự kết nối Zalo OA của họ.

Xem chi tiết tại [Hướng dẫn kết nối Zalo OA](/vi/channels/zalo/connect-zalo-oa).

## Xử lý sự cố thường gặp

<AccordionGroup>
  <Accordion title="Tin nhắn gửi đến Zalo OA không hiển thị trên Inbox">
    * Kiểm tra xem đường dẫn Webhook URL đã được cấu hình chính xác trên trang quản trị ứng dụng Zalo chưa.
    * Đảm bảo ứng dụng Zalo đã đăng ký đầy đủ các sự kiện bắt buộc (`send_msg`, `get_msg`, `follow`, `unfollow`).
    * Kiểm tra mã **Webhook Verify Token** cấu hình tại Zalo và Portal quản trị xem đã trùng khớp với nhau chưa.
  </Accordion>

  <Accordion title="Xác thực tên miền thất bại">
    * Đảm bảo máy chủ portal của bạn hỗ trợ giao thức bảo mật HTTPS và truy cập công khai bình thường.
    * Chờ từ 3-5 giây giữa mỗi lần bấm kiểm tra xác thực.
    * Thử chuyển đổi giữa các phương thức xác thực khác nhau (ví dụ: dùng DNS TXT record thay vì dùng thẻ HTML meta tag).
  </Accordion>

  <Accordion title="Lỗi trong quá trình cấp quyền xác thực (OAuth)">
    * Hãy chắc chắn tài khoản Zalo bạn đang đăng nhập giữ vai trò quản trị viên của trang Zalo OA cần kết nối.
    * Đảm bảo đường dẫn Callback URL trên cấu hình ứng dụng Zalo khớp hoàn toàn với đường dẫn trên Portal của bạn.
    * Kiểm tra lại mã **Client ID** và **Client Secret** cấu hình trên Portal đảm bảo khớp với thông tin App ID và Secret Key của ứng dụng trên Zalo Developers.
  </Accordion>

  <Accordion title="Làm thế nào để nhận hỗ trợ nếu sự cố vẫn chưa được khắc phục?">
    1. Kiểm tra lại lịch sử lỗi (logs) trực tiếp trên máy chủ portal để khoanh vùng nguyên nhân.
    2. Đảm bảo toàn bộ thông số trong trang Org Settings panel được nhập đầy đủ và chính xác.
    3. Đảm bảo tài khoản Zalo OA và tài khoản Zalo Developer đáp ứng đầy đủ điều kiện hoạt động của nền tảng Zalo.
    4. Liên hệ bộ phận hỗ trợ cộng đồng kèm theo mô tả chi tiết lỗi và ảnh chụp màn hình để được trợ giúp.
  </Accordion>
</AccordionGroup>