Chương 12: Hướng dẫn tích hợp Zalo OA với EzyOA để kết nối với Chatbot

Ở các chương trước, chúng ta đã xây dựng chatbot Ezyvora và lần lượt kết nối chatbot với các kênh giao tiếp khác nhau. Trong chương này, chúng ta sẽ tiếp tục mở rộng chatbot sang Zalo Official Account (Zalo OA) thông qua EzyOA. Sau khi hoàn thành, khách hàng có thể nhắn tin trực tiếp đến Zalo OA của doanh nghiệp. Tin nhắn sẽ được chuyển qua EzyOA và có thể tiếp tục được xử lý bởi chatbot đã cấu hình trên EzyPlatform.

Quá trình tích hợp sẽ gồm hai phần chính: tạo và cấu hình ứng dụng trên Zalo for Developers, sau đó đưa các thông tin cần thiết về EzyOA để kết nối hai hệ thống.

1. Đăng nhập Zalo for Developers

Trước tiên, truy cập Zalo for Developers và chọn Đăng nhập.

Zalo sẽ hiển thị mã QR. Sử dụng ứng dụng Zalo trên điện thoại để quét mã và đăng nhập vào tài khoản mà bạn sẽ sử dụng để quản lý ứng dụng.

Sau khi đăng nhập thành công, ảnh đại diện của tài khoản sẽ xuất hiện ở góc trên bên phải.

2. Tạo ứng dụng Zalo cho chatbot

Nhấn vào ảnh đại diện ở góc trên bên phải và chọn Thêm ứng dụng mới.

Tại màn hình Tạo ID ứng dụng mới, khai báo các thông tin cơ bản cho ứng dụng. Trong ví dụ này:

• Tên hiển thị: Ezyvora Chatbot
• Danh mục: Mạng xã hội
• Mô tả: thông tin ngắn gọn về ứng dụng.

Đồng ý với chính sách của Zalo, hoàn thành bước xác minh nếu được yêu cầu, sau đó nhấn Tạo ID ứng dụng.

Sau khi tạo thành công, chúng ta được chuyển đến trang quản lý ứng dụng.

3. Lấy ID ứng dụng và khóa bí mật

Trong phần Cài đặt, Zalo cung cấp hai thông tin quan trọng:

• ID ứng dụng
• Khóa bí mật của ứng dụng

Hai giá trị này sẽ được sử dụng khi cấu hình dịch vụ Zalo trong EzyOA.

4. Khởi tạo dịch vụ Zalo trong EzyOA

Quay lại trang quản trị EzyPlatform, truy cập EzyOA và mở phần quản lý Dịch vụ OA. Tạo hoặc chỉnh sửa dịch vụ có mã ZALO.

Tại đây, nhập ID ứng dụng vừa lấy từ Zalo vào trường ID ứng dụng và nhập khóa bí mật tương ứng vào Khóa bí mật.

Ngoài ra, EzyOA còn cung cấp các trường phục vụ quá trình xác thực và kết nối như Code Challenge, Code Verifier, khóa webhook và các cấu hình liên quan.

Ở bước đầu, chúng ta chủ yếu cần bảo đảm thông tin ứng dụng Zalo được khai báo chính xác. Sau đó nhấn Lưu.

5. Xác thực domain với Zalo

Trước khi sử dụng Callback URL của EzyOA, domain cần được Zalo xác thực.

Quay lại Zalo for Developers → Xác thực domain. Tại đây Zalo hỗ trợ xác thực Domain hoặc Tiền tố URL.

Trong ví dụ này, website quản trị sử dụng:

<code>https://fashion-admin.ezyplatform.com</code>

Nhập địa chỉ vào phần Tiền tố URL rồi nhấn Xác thực.

Nếu URL chưa được xác thực, Zalo sẽ hiển thị thông báo Chưa được xác thực. Chọn Xác thực ngay để tiếp tục.

6. Lấy mã xác thực website từ Zalo

Zalo cung cấp các phương thức xác thực quyền sở hữu website. Một cách là tải file HTML mà Zalo cung cấp lên website.

Trong trường hợp website đang được quản lý trực tiếp trên EzyPlatform, chúng ta có thể sử dụng cách thuận tiện hơn là Thêm thẻ meta vào trang web của bạn.

Mở phần này, Zalo sẽ cung cấp một thẻ dạng:

<code>&lt;meta name="zalo-platform-site-verification" content="..." /&gt;</code>

Sao chép chính xác thẻ meta mà Zalo cung cấp.

7. Thêm thẻ xác thực Zalo vào EzyPlatform

Quay lại trang quản trị EzyPlatform, vào EzySupport → Các cài đặt web → Mã nguồn.

Tại trường Bổ sung đầu trang, dán thẻ meta vừa lấy từ Zalo. Ví dụ:

<code>&lt;meta name="zalo-platform-site-verification" content="YOUR_VERIFICATION_CODE" /&gt;</code>

Sau đó lưu lại cấu hình để thẻ meta được đưa vào phần <head> của website.

Quay trở lại Zalo for Developers và nhấn Xác thực. Khi Zalo tìm thấy thẻ meta hợp lệ, hệ thống sẽ hiển thị thông báo: Xác thực thành công.

Đến đây, domain đã sẵn sàng để sử dụng cho Callback URL của ứng dụng.

8. Lấy Callback URL từ EzyOA

Tiếp theo, chúng ta cần kết nối quá trình cấp quyền của Zalo với EzyOA. Trong EzyOA, mở Chi tiết dịch vụ OA của dịch vụ ZALO.

Tại đây hệ thống cung cấp các URL cần thiết, trong đó có:

• Đường dẫn webhook
• Đường dẫn callback xác thực
• Auth URL

Trong ví dụ, đường dẫn callback có dạng:

<code>https://fashion.ezyplatform.com/oa/ZALO/auth-callback</code>

Sao chép giá trị tại Đường dẫn callback xác thực.

9. Khai báo Official Account Callback URL

Quay lại Zalo for Developers và truy cập Official Account → Thiết lập chung. Tại phần Thiết lập đường dẫn yêu cầu cấp quyền, tìm trường Official Account Callback Url.

Dán Đường dẫn callback xác thực vừa lấy từ EzyOA vào trường này. Ví dụ:

<code>https://fashion.ezyplatform.com/oa/ZALO/auth-callback</code>

Sau đó nhấn Lưu/Cập nhật.

Callback URL phải thuộc domain hoặc URL đã được Zalo xác thực. Nếu domain của Callback URL khác domain đã xác thực ở bước trước, Zalo có thể từ chối cấu hình. Vì vậy cần kiểm tra kỹ domain thực tế mà EzyOA sử dụng.

10. Cấu hình Code Challenge

Quá trình cấp quyền còn sử dụng Code Challenge và Code Verifier. Quay lại phần cấu hình dịch vụ ZALO trong EzyOA. Tạo hoặc lấy các giá trị:

• Code Challenge
• Code Verifier

Trong giao diện EzyOA có thể sử dụng nút Ngẫu nhiên để tạo giá trị cần thiết.

Lưu lại cấu hình. Sau đó quay lại Zalo for Developers → Official Account → Thiết lập chung. Nhập giá trị Code Challenge tương ứng. Khi Callback URL và Code Challenge đã được cập nhật, Zalo sẽ tạo lại Đường dẫn yêu cầu cấp quyền ở phía trên.

11. Yêu cầu quyền truy cập Zalo OA

Sau khi hoàn tất các cấu hình trên, bước tiếp theo là cấp quyền để ứng dụng có thể làm việc với Zalo Official Account.

Trong trang Official Account → Thiết lập chung, Zalo cho phép lựa chọn các quyền mà ứng dụng muốn yêu cầu từ OA, chẳng hạn quyền gửi tin nhắn, quản lý thông tin OA hoặc những API cần thiết cho chức năng của ứng dụng. Chỉ nên chọn các quyền thực sự cần thiết cho luồng tích hợp.

Sau đó sử dụng Đường dẫn yêu cầu cấp quyền được Zalo tạo ở đầu trang để bắt đầu quá trình cấp quyền.

12. Xử lý lỗi "User don't own any Official Accounts"

Trong quá trình lấy Access Token, bạn có thể gặp lỗi:

<code>error_code: -14068
error_name: User don't own any Official Accounts
description: User don't own any Official Accounts</code>

Lỗi này cho biết tài khoản Zalo đang thực hiện quá trình cấp quyền không có Official Account phù hợp để tiếp tục luồng cấp quyền.

Khi gặp trường hợp này, cần kiểm tra lại tài khoản Zalo đang đăng nhập ở bước cấp quyền và Zalo OA mà bạn muốn kết nối. Hãy bảo đảm đang sử dụng đúng tài khoản có quyền phù hợp đối với OA đó, sau đó thực hiện lại đường dẫn cấp quyền.

13. Thiết lập Webhook để Zalo gửi sự kiện về EzyOA

Sau khi hoàn thành cấu hình ứng dụng, domain và Callback URL, bước tiếp theo là thiết lập Webhook.

Webhook là địa chỉ mà Zalo sẽ sử dụng để gửi các sự kiện phát sinh từ Official Account về EzyOA. Ví dụ, khi khách hàng gửi tin nhắn cho OA, Zalo có thể gửi sự kiện đó đến Webhook của EzyOA để hệ thống tiếp tục xử lý.

Trên Zalo for Developers, chọn Webhook trong menu API và Cấp quyền.

Ở thời điểm này, trường Webhook URL chưa được cấu hình. Chúng ta cần sử dụng chính đường dẫn webhook mà EzyOA đã tạo cho dịch vụ Zalo.

14. Khai báo Webhook URL của EzyOA

Nhấn Thay đổi tại trường Webhook URL. Trong cửa sổ Cập nhật Webhook url, nhập đường dẫn webhook của dịch vụ Zalo trên EzyOA. Trong ví dụ của chúng ta:

<code>https://fashion.ezyplatform.com/api/v1/oa/ZALO/webhook</code>

Đây chính là Đường dẫn webhook đã xuất hiện trong trang chi tiết dịch vụ OA ở bước trước. Sau khi nhập URL, trước tiên nhấn Kiểm tra.

Zalo sẽ kiểm tra URL và hiển thị thông tin máy chủ tương ứng nếu có thể truy cập được địa chỉ này.

Nếu quá trình kiểm tra thành công, nhấn Cập nhật để lưu Webhook URL.

Webhook cần sử dụng địa chỉ HTTPS có thể truy cập từ Internet. Endpoint phía EzyOA cũng cần xử lý đúng yêu cầu Webhook của Zalo.

15. Kiểm tra Webhook và các sự kiện Zalo OA

Sau khi cập nhật thành công, quay lại trang Webhook. Lúc này địa chỉ EzyOA sẽ xuất hiện tại trường Webhook URL. Bên dưới, Zalo cung cấp thêm:

• OA Secret Key
• Webhook Retry
• Lọc cú pháp
• Danh sách sự kiện webhook

Phần Danh sách sự kiện webhook rất quan trọng vì nó quyết định những hoạt động nào của người dùng sẽ được Zalo gửi về EzyOA. Ví dụ có các sự kiện:

<code>user_send_location
user_send_image
user_send_link
user_send_text
user_send_sticker</code>

Trong đó, đối với chatbot hỏi đáp bằng văn bản, sự kiện đáng chú ý là:

<code>user_send_text</code>

Khi người dùng gửi một tin nhắn văn bản đến Zalo OA, Zalo có thể gửi sự kiện này đến Webhook URL đã cấu hình. EzyOA nhận dữ liệu và chuyển tiếp vào luồng xử lý chatbot.

Tùy vào chức năng cần triển khai, chúng ta có thể bật thêm những sự kiện cần thiết thay vì đăng ký toàn bộ.

16. Đồng bộ OA Secret Key về EzyOA

Ngoài Webhook URL, Zalo còn cung cấp OA Secret Key. Giá trị này cần được cấu hình tương ứng trong EzyOA để phục vụ quá trình xử lý và xác thực dữ liệu webhook.

Quay lại trang quản trị EzyPlatform, mở EzyOA → Dịch vụ OA → ZALO → Sửa. Tìm trường Khóa bí mật webhook. Nhập OA Secret Key từ phần Webhook của Zalo vào trường này.

Sau đó kiểm tra lại các thông tin quan trọng của dịch vụ Zalo:

• ID ứng dụng: lấy từ ứng dụng Zalo.
• Khóa bí mật: App Secret của ứng dụng Zalo.
• Khóa bí mật webhook: OA Secret Key trong phần Webhook.
• Code Challenge / Code Verifier: phục vụ quá trình cấp quyền.
• Trạng thái: chuyển sang Đã kích hoạt khi cấu hình đã sẵn sàng.

Cuối cùng nhấn Lưu.

17. Kiểm thử chatbot Ezyvora trực tiếp trên Zalo

Sau khi hoàn tất Webhook và các thông tin kết nối, chúng ta sẽ kiểm tra toàn bộ luồng bằng cách gửi tin nhắn thực tế đến Zalo OA.

Trong bài này, quá trình kiểm thử được quan sát ở hai phía:

• Phía khách hàng: nơi người dùng gửi tin nhắn và nhận câu trả lời từ chatbot.
• Phía quản trị Zalo OA: nơi doanh nghiệp theo dõi lại cuộc hội thoại giữa khách hàng và OA.

17.1. Gửi tin nhắn từ phía khách hàng

Đầu tiên, từ giao diện nhắn tin của khách hàng, gửi một câu đơn giản như:

<code>xin chào</code>

Sau khi tin nhắn được gửi đến Zalo OA, chatbot Ezyvora tiếp nhận yêu cầu và tự động phản hồi nội dung chào hỏi, đồng thời giới thiệu những nội dung mà chatbot có thể hỗ trợ như tư vấn sản phẩm, báo giá, hỗ trợ kỹ thuật hoặc kết nối với bộ phận hỗ trợ.

Kết quả này cho thấy tin nhắn từ Zalo đã được chuyển qua luồng tích hợp và chatbot có thể gửi câu trả lời trở lại cho người dùng.

17.2. Kiểm tra khả năng tư vấn bằng dữ liệu của Ezyvora

Tiếp theo, chúng ta thử một yêu cầu cụ thể hơn:

<code>tôi muốn mua gói chuyên nghiệp của ezyvora</code>

Chatbot nhận biết nhu cầu mua hàng và trả về thông tin phù hợp về Gói Chuyên Nghiệp, bao gồm hướng dẫn truy cập trang chi tiết gói và lựa chọn tiếp tục mua hoặc đăng ký tư vấn.

Bước kiểm thử này không chỉ xác nhận việc gửi và nhận tin nhắn đã hoạt động mà còn cho thấy chatbot Ezyvora có thể tiếp tục sử dụng kỹ năng và dữ liệu đã được cấu hình trước đó để xử lý yêu cầu của khách hàng trên kênh Zalo.

Nói cách khác, chúng ta không cần xây dựng lại một chatbot riêng cho Zalo. Zalo đóng vai trò là một kênh giao tiếp mới, còn phần xử lý hội thoại vẫn được thực hiện bởi chatbot Ezyvora.

17.3. Kiểm tra cuộc hội thoại từ phía quản trị Zalo OA

Cuối cùng, đăng nhập vào trang quản trị Zalo Official Account và mở phần Trò chuyện OA.

Tại đây, chúng ta có thể thấy lại toàn bộ cuộc hội thoại vừa kiểm thử, bao gồm tin nhắn của khách hàng và các câu trả lời tương ứng được gửi từ OA.

Như vậy, doanh nghiệp vẫn có thể theo dõi cuộc trò chuyện ngay trên giao diện quản trị của Zalo OA, trong khi chatbot Ezyvora đảm nhiệm việc xử lý và phản hồi tự động.

Khi tin nhắn của khách hàng, câu trả lời của chatbot và lịch sử hội thoại đều xuất hiện đúng ở hai phía, chúng ta có thể xác nhận luồng tích hợp Zalo OA – EzyOA – EzyChat – chatbot Ezyvora đã hoạt động theo kịch bản kiểm thử.

Kết luận

Đến đây, chatbot Ezyvora không còn chỉ hoạt động trên website. Khách hàng có thể bắt đầu cuộc trò chuyện trực tiếp từ Zalo, trong khi doanh nghiệp vẫn có thể theo dõi hội thoại trên trang quản trị Zalo OA.

Quan trọng hơn, chatbot vẫn sử dụng chung kỹ năng và dữ liệu đã xây dựng cho Ezyvora. Điều này giúp doanh nghiệp mở rộng thêm một điểm chạm với khách hàng mà không phải xây dựng lại toàn bộ hệ thống chatbot cho từng kênh.