Guide to Integrating WhatsApp Cloud API into Chatwoot (Detailed Manual Flow)

Trong kỷ nguyên số hóa hiện nay, việc chăm sóc khách hàng đa kênh (Omnichannel) là yếu tố sống còn đối với mọi doanh nghiệp. WhatsApp, với hơn 2 tỷ người dùng trên toàn cầu, là một trong những kênh giao tiếp quan trọng nhất mà bạn không thể bỏ qua. Khi kết hợp sức mạnh của WhatsApp với Chatwoot – nền tảng Omnichannel Customer Engagement mã nguồn mở hàng đầu – doanh nghiệp của bạn có thể quản lý hàng ngàn tin nhắn từ khách hàng một cách hiệu quả, tập trung và chuyên nghiệp.

Bài viết này sẽ hướng dẫn bạn chi tiết từng bước để tích hợp WhatsApp Cloud API vào Chatwoot theo phương pháp thủ công (Manual Flow). Đây là cách tiếp cận giúp bạn nắm quyền kiểm soát hoàn toàn dữ liệu và cấu hình của mình mà không phụ thuộc vào các bên thứ ba (BSP) đắt đỏ.

Tại sao nên sử dụng WhatsApp Cloud API với Chatwoot?

Trước khi đi vào chi tiết kỹ thuật, hãy cùng điểm qua một số lợi ích to lớn khi bạn thực hiện việc tích hợp này:

• Cost savings: WhatsApp Cloud API được lưu trữ trực tiếp trên hạ tầng của Meta, giúp loại bỏ chi phí trung gian mà trước đây bạn phải trả cho các BSP như Twilio hay MessageBird.
• Tốc độ và độ ổn định cao: Kết nối trực tiếp với Meta đảm bảo độ trễ thấp nhất và tính ổn định cao nhất cho hệ thống tin nhắn của bạn.
• Centralized management: Chatwoot cho phép bạn gom tin nhắn từ WhatsApp, Facebook, Email, Live Chat vào một giao diện duy nhất, giúp nhân viên hỗ trợ không phải chuyển đổi giữa nhiều ứng dụng.
• Tự động hóa: Tận dụng các tính năng của Chatwoot như Chatbot, Automation Rules và Canned Responses để trả lời khách hàng nhanh chóng.

Yêu cầu chuẩn bị (Prerequisites)

Để quá trình cài đặt diễn ra suôn sẻ, bạn cần chuẩn bị sẵn các tài nguyên sau:

1. Tài khoản Meta Developer: Nếu chưa có, hãy đăng ký miễn phí tại developers.facebook.com. Đây là nơi bạn quản lý các ứng dụng kết nối với hệ sinh thái Facebook/Instagram/WhatsApp.
2. Số điện thoại hợp lệ: Bạn cần một số điện thoại có khả năng nhận tin nhắn SMS hoặc cuộc gọi thoại để xác minh.
   • Important notes: Số điện thoại này không được đang liên kết với bất kỳ tài khoản WhatsApp cá nhân hoặc WhatsApp Business App nào trên điện thoại. Nếu có, bạn phải xóa tài khoản WhatsApp trên điện thoại trước khi dùng nó cho API.
3. Tài khoản Facebook Business: Truy cập được vào business.facebook.com để quản lý tài sản doanh nghiệp.

Bước 1: Thiết lập Hồ sơ Doanh nghiệp (Business Profile)

Bước đầu tiên là tạo danh tính cho doanh nghiệp của bạn trên nền tảng Meta. Điều này giúp Meta xác thực doanh nghiệp và cấp quyền truy cập vào các tính năng cao cấp của WhatsApp API.

1. Access business.facebook.com.
2. Nếu bạn là người mới, hãy tạo một Business Portfolio (trước đây gọi là Business Manager Account).
3. Điền đầy đủ thông tin pháp lý của doanh nghiệp như Tên doanh nghiệp, Email doanh nghiệp, và Địa chỉ. Việc thông tin chính xác sẽ giúp quá trình xác minh doanh nghiệp (Business Verification) sau này diễn ra nhanh hơn, mặc dù với mức sử dụng cơ bản bạn có thể chưa cần xác minh ngay.

Bước 2: Tạo ứng dụng Facebook App

Tương tự như khi bạn tạo một “cổng kết nối” kỹ thuật, App trên Facebook Developers là nơi chứa các cấu hình API.

1. Visit the page My Apps và nhấn nút màu xanh Create App.
2. Tại màn hình “What do you want your app to do?”, chọn tùy chọn Other (Khác). Nhấn Next.
3. Tại màn hình “Select an app type”, chọn Business. Đây là loại ứng dụng dành cho việc quản lý Pages, Events và WhatsApp Business API. Nhấn Next.
4. Tại phần “Details”:
   • App Name: Đặt tên dễ nhớ, ví dụ “Chatwoot WhatsApp Connect”.
   • App Contact Email: Email của bạn.
   • Business Portfolio: Chọn tài khoản Business bạn đã tạo ở Bước 1. Đây là bước bắt buộc để sử dụng WhatsApp API trên môi trường Production.
5. Press Create app để hoàn tất. Bạn có thể cần nhập mật khẩu Facebook để xác nhận.

Bước 3: Thêm sản phẩm WhatsApp vào ứng dụng

Sau khi tạo App, bạn sẽ được đưa đến bảng điều khiển (App Dashboard). Lúc này App của bạn chưa có chức năng gì cả, bạn cần thêm “Sản phẩm” WhatsApp vào.

1. Kéo xuống tìm mục có tên WhatsApp trong danh sách sản phẩm. Nhấn nút Set up.
2. Meta sẽ yêu cầu bạn chọn hoặc tạo mới một Meta Business Account. Hãy chọn tài khoản Business của bạn.
3. Press Continue. Hệ thống sẽ mất vài giây để thiết lập môi trường WhatsApp Cloud API cho bạn.

Bước 4: Tạo Permanent Access Token (Token truy cập vĩnh viễn)

Đây là bước quan trọng nhất và thường hay bị nhầm lẫn nhất. Mặc định, Meta cung cấp cho bạn một “Temporary Access Token” (Token tạm thời) có thời hạn chỉ 24 giờ. Nếu bạn dùng token này để nhập vào Chatwoot, kết nối sẽ bị ngắt sau một ngày. Bạn bắt buộc phải tạo một “System User” (Người dùng hệ thống) để lấy Token vĩnh viễn.

1. Access Business Settings.
2. Ở menu bên trái, tìm mục Users > System Users.
3. Press the button Add. Sẽ có một popup hiện ra. Hãy đọc kỹ và nhấn chấp nhận các điều khoản.
4. Đặt tên cho System User, ví dụ “Chatwoot Admin”. Ở phần System User Role, select Admin. Nhấn Create System User.
5. Sau khi tạo xong, bạn cần gán tài sản (App) cho user này. Nhấn nút Add Assets.
6. Trong cửa sổ hiện ra, chọn mục Apps, sau đó chọn tên Ứng dụng bạn đã tạo ở Bước 2.
7. Bật tùy chọn Full Control (Manage App) để cấp toàn quyền. Nhấn Save Changes.
8. Bây giờ, quay lại trang danh sách System Users, chọn user bạn vừa tạo. Nhấn nút Generate new token.
9. Chọn App của bạn từ danh sách thả xuống.
10. Cấp quyền (Permissions): Bạn cần tìm và tích chọn chính xác 3 quyền sau (rất quan trọng):
    • whatsapp_business_messaging: Cho phép gửi và nhận tin nhắn.
    • whatsapp_business_management: Cho phép quản lý thông tin doanh nghiệp WhatsApp.
    • whatsapp_business_manage_events: Cho phép nhận các sự kiện webhook (tin nhắn đến, trạng thái gửi, v.v.).
11. Press Generate Token. Một chuỗi mã dài sẽ hiện ra. Hãy copy và lưu trữ nó ở nơi an toàn ngay lập tức, vì Facebook sẽ không hiển thị lại mã này lần thứ hai. Đây chính là “API Key” mà bạn sẽ nhập vào Chatwoot.

Bước 5: Cấu hình số điện thoại WhatsApp

Bạn cần khai báo số điện thoại thực tế sẽ dùng để chat với khách hàng.

1. Quay lại trang App Dashboard trên developers.facebook.com.
2. Ở menu trái, chọn WhatsApp > API Setup.
3. Scroll down to the section Step 5: Add a phone number, nhấn nút Add phone number.
4. Điền thông tin hồ sơ WhatsApp:
   • Display Name: Tên hiển thị với khách hàng (Ví dụ: Chăm sóc khách hàng ABC).
   • Category: Chọn lĩnh vực kinh doanh phù hợp.
5. Nhập số điện thoại của bạn và chọn phương thức xác minh (SMS hoặc Voice Call).
6. Nhập mã OTP để hoàn tất xác minh.
7. Sau khi thành công, bạn sẽ thấy số điện thoại của mình hiện trong danh sách. Tại đây, hãy copy hai thông số quan trọng: Phone Number ID and WhatsApp Business Account ID.

Bước 6: Kết nối với Chatwoot

Đã đến lúc ghép nối mọi thứ lại với nhau trên giao diện Chatwoot.

1. Đăng nhập vào hệ thống Chatwoot của bạn với quyền Administrator.
2. Go to Settings (Cài đặt – biểu tượng bánh răng) > Inboxes > Add Inbox.
3. Select the icon WhatsApp.
4. Tại mục API Provider, chọn WhatsApp Cloud (Lưu ý đừng chọn nhầm Twilio hay 360Dialog).
5. Điền form cấu hình:
   • Phone Number: Nhập số điện thoại đã xác minh (Chỉ nhập số, bao gồm mã quốc gia, không có dấu cộng hay khoảng trắng. Ví dụ: 84912345678).
   • Phone Number ID: Dán ID bạn đã lấy ở Bước 5.
   • Business Account ID: Dán ID bạn đã lấy ở Bước 5.
   • API Key: Dán mã Permanent Access Token bạn đã tạo và lưu ở Bước 4.
6. Press Create WhatsApp Channel.
7. Bước tiếp theo, chọn các nhân viên (Agents) sẽ quản lý hộp thư này. Nhấn Add agents.
8. Màn hình cuối cùng sẽ cung cấp cho bạn Webhook URL and Webhook Verify Token. Hãy giữ nguyên màn hình này hoặc copy chúng lại.

Bước 7: Cấu hình Webhook

Việc nhập Token ở Bước 6 mới chỉ giúp Chatwoot gửi tin nhắn đi. Để Chatwoot nhận được tin nhắn khách hàng gửi đến, bạn cần khai báo địa chỉ Webhook với Meta.

1. Quay lại trang Facebook App Dashboard.
2. Tại menu bên trái, trong mục WhatsApp > chọn Configuration.
3. Tìm phần có tiêu đề Webhook, nhấn nút Edit.
4. Một cửa sổ popup sẽ hiện ra:
   • Callback URL: Dán Webhook URL mà Chatwoot đã cung cấp (thường có dạng https://domain-cua-ban.com/webhooks/whatsapp/...).
   • Verify Token: Dán Verify Token từ Chatwoot.
5. Press Verify and Save. Nếu thông tin đúng, cửa sổ sẽ đóng lại và hiện dấu tích xanh. Nếu báo lỗi, hãy kiểm tra lại URL có thể truy cập công khai không (nếu bạn đang cài Chatwoot localhost thì cần dùng ngrok).
6. Chưa xong! Bạn cần đăng ký các sự kiện muốn nhận. Tại mục Webhook fields, click Manage.
7. Tại cột Subscribe, tìm dòng messages và tích chọn nó. Đây là sự kiện bắt buộc để nhận nội dung tin nhắn. Ngoài ra, bạn có thể chọn thêm message_deliveries, message_reads để theo dõi trạng thái đã gửi/đã xem.
8. Press Done.

Hoàn tất và Kiểm tra

Chúc mừng! Bạn đã hoàn thành quy trình tích hợp WhatsApp Cloud API vào Chatwoot. Bây giờ, hệ thống đã sẵn sàng hoạt động.

Cách kiểm tra:

• Dùng một số điện thoại cá nhân khác, gửi tin nhắn “Hello” tới số điện thoại doanh nghiệp bạn vừa cài đặt.
• Mở Dashboard Chatwoot, bạn sẽ thấy tin nhắn mới xuất hiện trong Inbox WhatsApp.
• Thử trả lời lại từ Chatwoot, điện thoại cá nhân sẽ nhận được phản hồi ngay lập tức.

Một số lưu ý khi vận hành (Troubleshooting)

• Quy tắc 24 giờ: WhatsApp áp dụng chính sách phiên làm việc 24 giờ. Nếu khách hàng không nhắn tin cho bạn trong vòng 24 giờ qua, bạn không thể gửi tin nhắn tự do cho họ. Bạn phải sử dụng Template Messages (Tin nhắn mẫu) đã được Meta duyệt trước để bắt đầu hội thoại.
• Cập nhật Token: Nếu bạn lỡ dùng Token tạm thời, kết nối sẽ mất sau 24h. Hãy vào Chatwoot > Settings > Inboxes > WhatsApp > Configuration và cập nhật lại Token vĩnh viễn mới.
• Lỗi không nhận tin nhắn: Hãy kiểm tra lại phần Webhook xem đã Subscribe sự kiện messages chưa. Đây là lỗi phổ biến nhất.

Hy vọng hướng dẫn này giúp bạn làm chủ được kênh giao tiếp WhatsApp trên Chatwoot. Chúc doanh nghiệp của bạn tăng trưởng mạnh mẽ với hệ thống chăm sóc khách hàng mới!