Kết nối Zalo OA vào hộp thư ChatHub

Bài này giải quyết việc gì#

Kênh Zalo OA của ChatHub nhận tin nhắn khách gửi tới một Zalo Official Account rồi cho nhân viên trả lời ngay trong hộp thư chung — kèm ảnh, tệp và vị trí khách chia sẻ. Kênh đi qua Open API chính thức của Zalo, khác hẳn kênh Zalo cá nhân (đăng nhập bằng QR): OA là tài khoản doanh nghiệp, ổn định và đúng điều khoản của Zalo.

Phần cấu hình chia làm hai phía. Bên Zalo for Developers, bạn chuẩn bị một ứng dụng, cho OA cấp quyền cho ứng dụng đó rồi lấy ra ba giá trị: App ID, Secret Key và refresh token. Bên ChatHub, bạn dán ba giá trị này vào, chép Webhook URL mà ChatHub cấp sẵn sang Zalo, rồi bấm Kết nối. Cả quy trình mất khoảng mười lăm phút.

Để nhận được tin nhắn qua webhook, bản cài ChatHub phải có một tên miền HTTPS công khai mà Internet truy cập được. Zalo chỉ gửi sự kiện tới địa chỉ HTTPS, nên máy chủ chạy sau NAT hoặc chỉ có địa chỉ nội bộ sẽ không nhận được tin cho tới khi có tên miền công khai.

1. Chuẩn bị trước khi bắt đầu#

1. 1

   Một Zalo Official Account đã được duyệt, và bạn là quản trị viên của OA đó (để cấp quyền cho ứng dụng).

2. 2

   Một tài khoản Zalo dùng để đăng nhập Zalo for Developers tại địa chỉ developers.zalo.me.

3. 3

   Bản cài ChatHub có tên miền HTTPS công khai (ví dụ https://chat.congty.com). Nếu chưa có, hãy cấu hình tên miền trước khi làm bước webhook.

4. 4

   Quyền quản trị trong ChatHub để mở mục Kênh và thêm tài khoản mới.

2. Chuẩn bị ứng dụng và cấp quyền OA (trên Zalo for Developers)#

Bước này làm hoàn toàn trên Zalo for Developers. Mục tiêu là có một ứng dụng, và cho Official Account của bạn cấp quyền quản lý cho ứng dụng đó — đây là điều kiện để lấy được refresh token ở bước sau.

1. 1

   Mở developers.zalo.me và đăng nhập bằng tài khoản Zalo của bạn.

2. 2

   Tạo một ứng dụng mới (Create Application), đặt tên gợi nhớ cho ứng dụng.

3. 3

   Trong ứng dụng, thêm sản phẩm Official Account rồi liên kết OA của bạn: chọn OA và cấp quyền cho ứng dụng quản lý OA. Bước cấp quyền phải do quản trị viên OA xác nhận.

4. 4

   Xác thực tên miền của ứng dụng: khai domain của bản cài ChatHub (phần tên miền HTTPS công khai) vào mục domain của ứng dụng, theo hướng dẫn xác thực của Zalo. Thiếu bước này, Zalo có thể từ chối gửi webhook về địa chỉ của bạn.

3. Lấy App ID, Secret Key và refresh token#

ChatHub cần đúng ba giá trị. App ID và Secret Key là của ứng dụng; refresh token là thứ đại diện cho quyền mà OA vừa cấp cho ứng dụng.

1. 1

   App ID và Secret Key: mở trang thông tin ứng dụng trên Zalo for Developers. App ID hiện ngay ở phần thông tin chung; Secret Key nằm ở mục khoá bí mật của ứng dụng. Chép cả hai.

2. 2

   Refresh token: sau khi OA cấp quyền cho ứng dụng, Zalo phát hành một mã uỷ quyền; đổi mã đó lấy cặp access token + refresh token theo luồng OAuth v4 của Zalo (hoặc dùng công cụ hỗ trợ mà Zalo cung cấp cho việc lấy token của OA). Thứ ChatHub cần là refresh token.

3. 3

   Giữ ba giá trị này để dán vào ChatHub ở mục 5. Đừng gửi chúng qua chat hay email.

4. Thêm kênh Zalo OA trong ChatHub#

1. 1

   Mở ChatHub, vào Quản trị → Kênh rồi bấm Thêm tài khoản ở góc trên bên phải.

2. 2

   Trong cột Loại kênh của hộp thoại, chọn Zalo OA (Official Account).

3. 3

   Đặt Tên kênh gợi nhớ, ví dụ Zalo OA cửa hàng — tên này chỉ hiện trong ChatHub để phân biệt các kênh cùng loại.

4. 4

   Dán App ID vào ô App ID, Secret Key vào ô Secret Key, refresh token vào ô Refresh token. Ô Access token là tuỳ chọn — để trống thì ChatHub tự lấy access token từ refresh token khi kết nối.

1. 1

   Kéo xuống cuối biểu mẫu tới khối Webhook URL cho ứng dụng Zalo. Bấm Chép để lấy địa chỉ webhook — địa chỉ này có dạng https://<tên-miền-của-bạn>/api/channels/webhooks/zalo-oa và dùng chung cho mọi kênh OA của bản cài.

2. 2

   Sang Zalo for Developers, mở ứng dụng ở mục Official Account → Webhook, dán địa chỉ vừa chép vào ô Webhook URL và lưu lại. Đảm bảo tên miền của ứng dụng đã được xác thực (mục 2).

3. 3

   Quay lại ChatHub, bấm Tạo tài khoản. Hộp thoại cấu hình kênh mở ra, trạng thái lúc này là Đã ngắt.

5. Kết nối và kiểm tra#

1. 1

   Trong hộp thoại cấu hình kênh vừa mở, bấm Kết nối. ChatHub gọi sang Zalo để kiểm chứng bộ khoá và đọc danh tính OA.

2. 2

   Sau vài giây, trạng thái chuyển từ Đã ngắt sang Đang hoạt động, còn tên và ảnh đại diện của kênh được thay bằng tên và ảnh của OA.

3. 3

   Từ điện thoại, nhắn thử một tin tới OA. Mở Tin nhắn trong ChatHub: hội thoại mới xuất hiện kèm huy hiệu Zalo. Trả lời từ ChatHub và kiểm tra tin về đúng khách trên Zalo.

Khi có trục trặc, ChatHub ghi thẳng nguyên nhân lên kênh thay vì mã lỗi thô của Zalo:

1. 1

   Zalo từ chối làm mới access token — refresh token đã hết hạn hoặc đã bị dùng ở nơi khác (ví dụ ai đó lấy lại token trên Zalo for Developers). Cấp quyền lại cho ứng dụng để lấy refresh token mới, rồi nhập lại bộ khoá theo mục 7.

2. 2

   Thiếu App ID, Secret Key hoặc refresh token — quay lại mục 4 và điền đủ ba giá trị.

3. 3

   Webhook không nhận được tin — kiểm tra Webhook URL đã dán đúng bên Zalo, tên miền ứng dụng đã xác thực, và APP_URL của bản cài là địa chỉ HTTPS công khai.

6. Nhập lại bộ khoá khi cần#

Refresh token của Zalo dùng một lần và không xin lại được qua API. Nếu chuỗi làm mới đứt — mất một lượt xoay token, hoặc bạn vừa đổi Secret Key bên Zalo — thì thay khoá tại chỗ, không cần xoá kênh (xoá kênh sẽ mất toàn bộ hội thoại của OA).

1. 1

   Mở kênh Zalo OA trong mục Kênh, kéo xuống phần Bộ khoá ứng dụng.

2. 2

   Nhập lại App ID, Secret Key và refresh token mới (Access token để trống cũng được), rồi bấm Lưu bộ khoá.

3. 3

   Kênh trở về trạng thái Đã ngắt. Bấm Kết nối để kiểm chứng bộ khoá mới. Hội thoại và tin nhắn cũ vẫn giữ nguyên.

7. Phạm vi và giới hạn cần biết#

1. 1

   Chỉ chat một-một: OA trò chuyện riêng với từng người quan tâm, không có tin nhắn nhóm.

2. 2

   Ảnh: tối đa 1 MB mỗi ảnh (JPG/PNG). Ảnh lớn hơn bị Zalo từ chối; ChatHub báo để bạn thu nhỏ hoặc gửi thành tệp.

3. 3

   Tệp: tối đa 5 MB mỗi tệp. Tệp lớn hơn nên gửi bằng đường dẫn tải về.

4. 4

   Không gửi được video qua API tin tư vấn của Zalo OA; ChatHub chặn sớm và gợi ý gửi ảnh, tệp hoặc dán đường dẫn video.

5. 5

   Không kéo được tin nhắn cũ: Zalo OA không có API đọc lịch sử, nên kênh chỉ nhận tin từ lúc kết nối trở đi.

6. 6

   Không có biên nhận đã đọc cho OA, nên hộp thư không hiển thị trạng thái khách đã xem tin.

7. 7

   Chữ ký bảo mật: mỗi sự kiện Zalo gửi về đều được ChatHub kiểm chữ ký X-ZEvent-Signature bằng Secret Key của ứng dụng, nên không ai giả được tin nhắn vào hộp thư.

Xem thêm: các loại kênh ChatHub hỗ trợ ↗