API Đám mây

Nền tảng WhatsApp Business > API Đám mây

Tổng quan

Với API Đám mây, do Meta cung cấp, các doanh nghiệp vừa và lớn có thể giao tiếp với khách hàng trên quy mô lớn. Khi sử dụng API này, doanh nghiệp có thể xây dựng các hệ thống kết nối hàng nghìn khách hàng với tổng đài hoặc bot, từ đó thúc đẩy hoạt động giao tiếp cả theo lập trình lẫn thủ công. Ngoài ra, doanh nghiệp có thể tích hợp API này với vô số hệ thống phụ trợ, chẳng hạn như nền tảng marketing và CRM.

Giao thức HTTP

API Đám mây được xây dựng dựa trên API Đồ thị. Vì vậy, yêu cầu được thể hiện thông qua giao thức HTTP cũng như tổ hợp các thông số URL, tiêu đề và nội dung yêu cầu. Ví dụ: một lệnh gọi phổ biến đến API Đám mây từ dòng lệnh dựa trên UNIX có dạng như sau:

curl 'https://graph.facebook.com/v17.0/106540352242922/messages' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "+16505555555",
  "type": "text",
  "text": {
    "preview_url": true,
    "body": "Here'\''s the info you requested! https://www.meta.com/quest/quest-3/"
  }
}'

Nếu bạn chưa quen dùng API Đồ thị, hãy tham khảo tài liệu về API Đồ thị của chúng tôi để tìm hiểu các kiến thức cơ bản. Điểm khác biệt chính giữa API Đồ thị và API Đám mây là loại mã truy cập bạn thường dùng, quyền truy cập tài nguyên, cú pháp yêu cầu và cú pháp webhook. Những điểm khác biệt này sẽ được mô tả chi tiết hơn trong các phần thích hợp của bộ tài liệu về API Đám mây.

Tài nguyên

Bạn sẽ tương tác với các tài nguyên chính sau đây khi sử dụng API này.

Hồ sơ doanh nghiệp

Để sử dụng API này, bạn phải có hồ sơ doanh nghiệp. Nếu bạn không có, hệ thống sẽ nhắc bạn tạo hồ sơ doanh nghiệp trong quy trình Bắt đầu. Hồ sơ doanh nghiệp đóng vai trò là vùng chứa cho Tài khoản WhatsApp Business (WABA) và số điện thoại của doanh nghiệp bạn.

Để tìm hiểu thêm về hồ sơ doanh nghiệp, hãy tham khảo bài viết Giới thiệu về hồ sơ doanh nghiệp trong Meta Business Suite trong trung tâm trợ giúp của chúng tôi.

Tài khoản WhatsApp Business

Tài khoản WhatsApp Business đại diện cho doanh nghiệp trên Nền tảng WhatsApp Business và chủ yếu bao gồm siêu dữ liệu về một doanh nghiệp cụ thể. Hầu hết các tài nguyên khác trên WhatsApp như Số điện thoại WhatsApp Business và Mẫu tin nhắn WhatsApp đều được liên kết với một WABA.

Bạn có thể làm theo các bước trong tài liệu hướng dẫn Bắt đầu của chúng tôi để tạo một WABA. Để tìm hiểu thêm về WABA và các giới hạn của WABA, hãy xem bài viết Tài khoản WhatsApp Business.

Số điện thoại WhatsApp Business

Số điện thoại WhatsApp Business (số điện thoại của doanh nghiệp) đại diện cho một số điện thoại thực. Sau khi số này được đăng ký để sử dụng với API Đám mây, bạn có thể dùng số này để gửi và nhận tin nhắn đến/từ người dùng WhatsApp thông qua API này.

Số điện thoại của doanh nghiệp chủ yếu bao gồm siêu dữ liệu về chính số điện thoại đó và doanh nghiệp của bạn. Siêu dữ liệu này có thể hiển thị trong ứng dụng WhatsApp khi người dùng tương tác với số điện thoại của doanh nghiệp bạn.

Bạn có thể làm theo các bước trong tài liệu hướng dẫn Bắt đầu của chúng tôi để tạo một số điện thoại của doanh nghiệp. Lưu ý rằng có một số hạn chế và giới hạn đối với số điện thoại của doanh nghiệp và cách sử dụng các số điện thoại đó. Những hạn chế và giới hạn này được mô tả chi tiết trong tài liệu về Số điện thoại của doanh nghiệp.

Mẫu tin nhắn WhatsApp

Mẫu tin nhắn WhatsApp (mẫu) là các mẫu tùy chỉnh được mà bạn có thể tạo qua API này bằng cách sử dụng những thành phần mẫu khác nhau. Các mẫu này sẽ tự động được xét duyệt sau khi tạo xong. Nếu được phê duyệt, bạn có thể sử dụng các mẫu này trong tin nhắn mẫu.

Bạn có thể gửi 2 loại tin nhắn cơ bản qua API này: tin nhắn dạng tự do và tin nhắn mẫu. Trong đó, tin nhắn mẫu có mức độ hạn chế cao nhất do loại tin nhắn này yêu cầu sử dụng Mẫu tin nhắn WhatsApp đã được phê duyệt. Tuy nhiên, vì các mẫu phải trải qua quy trình xét duyệt và phải được phê duyệt thì mới có thể sử dụng, nên tin nhắn mẫu ít có khả năng nhận được phản hồi tiêu cực từ người nhận. Điều này có thể ảnh hưởng hoàn toàn đến khả năng bạn nhắn tin cho khách hàng.

Để tìm hiểu thêm về mẫu, hãy tham khảo tài liệu về Mẫu của chúng tôi.

Webhooks

Webhooks là phần tải dữ liệu JSON đơn giản được gửi đến một điểm cuối công khai trên máy chủ của bạn thông qua giao thức HTTP. API Đám mây chủ yếu dựa vào webhook vì nội dung của mọi tin nhắn do người dùng WhatsApp gửi đến số điện thoại của doanh nghiệp bạn sẽ được gửi dưới dạng webhook. Ngoài ra, hệ thống sẽ báo cáo tất cả thông tin cập nhật về trạng thái phân phối tin nhắn đi thông qua webhook.

Lưu ý rằng chúng tôi cung cấp ứng dụng webhook mẫu mà bạn có thể sao chép trên Glitch và dùng trong quá trình thử nghiệm. Ứng dụng này chỉ kết xuất phần tải dữ liệu webhook trực tiếp đến một bảng điều khiển để bạn có thể xem nội dung. Lưu ý rằng bạn vẫn cần tạo điểm cuối riêng trên máy chủ của mình vào một thời điểm nào đó để xử lý các webhook theo logic kinh doanh của chính bạn.

Hãy xem bài viết Webhooks của Meta để tìm hiểu thêm về webhook và cách xử lý chúng. Ngoài ra, hãy tham khảo tài liệu Webhooks cho Tài khoản WhatsApp Business của chúng tôi.

Tài nguyên thử nghiệm

Sau khi bạn hoàn tất các bước đầu tiên trong tài liệu hướng dẫn Bắt đầu, hệ thống sẽ tự động tạo cho bạn một WABA thử nghiệm và số điện thoại thử nghiệm của doanh nghiệp.

WABA thử nghiệm và số điện thoại thử nghiệm rất hữu ích cho mục đích thử nghiệm vì chúng bỏ qua hầu hết các giới hạn nhắn tin và không yêu cầu có phương thức thanh toán trong hồ sơ để gửi tin nhắn mẫu.

Bạn có thể xóa hồ sơ doanh nghiệp và các tài nguyên thử nghiệm tương ứng nếu:

  • bạn là quản trị viên trên hồ sơ doanh nghiệp được liên kết với ứng dụng
  • hồ sơ doanh nghiệp này không được liên kết với ứng dụng nào khác
  • hồ sơ doanh nghiệp này không được liên kết với WABA nào khác
  • WABA này không được liên kết với số điện thoại nào khác của doanh nghiệp.

Cách xóa hồ sơ doanh nghiệp và các tài nguyên thử nghiệm tương ứng:

  1. Chuyển đến Bảng điều khiển ứng dụng > WhatsApp > Cấu hình.
  2. Tìm phần Tài khoản thử nghiệm.
  3. Nhấp vào nút Xóa.

Xác thực và ủy quyền

Mã truy cập

API này hỗ trợ 3 loại mã:

  • Mã truy cập dành cho Người dùng hệ thống
  • Mã truy cập dành cho Người dùng hệ thống của Tiện ích tích hợp cho doanh nghiệp
  • Mã truy cập dành cho Người dùng

Hãy xem phần Mã truy cập của chúng tôi để xác định loại mã bạn nên sử dụng. Lưu ý rằng bạn nên chuyển mã qua tiêu đề yêu cầu, thay vì qua thông số chuỗi truy vấn.

Quyền

API này dựa vào các quyền API Đồ thị sau đây. Các quyền cụ thể cần thiết cho ứng dụng của bạn phụ thuộc vào điểm cuối mà ứng dụng đó sẽ dùng.

  • business_management - cần thiết nếu tương tác với hồ sơ doanh nghiệp.
  • whatsapp_business_management - cần thiết nếu tương tác với một WABA và dữ liệu phân tích hoặc bất kỳ mẫu/số điện thoại nào của doanh nghiệp cho WABA đó.
  • whatsapp_business_messaging - cần để gửi và nhận tin nhắn đến/từ người dùng WhatsApp.

Các quyền này thường được cấp khi tạo mã truy cập trong Meta Business Suite. Hãy xem phần tạo mã trong tài liệu về Mã truy cập của chúng tôi.

Lập phiên bản

Tính năng lập phiên bản sử dụng giao thức lập phiên bản của API Đồ thị. Nghĩa là tất cả yêu cầu điểm cuối đều có thể chứa số phiên bản và mỗi phiên bản sẽ dùng được trong khoảng 2 năm, sau đó ngừng hoạt động và không thể gọi được nữa.

Thông lượng

Đối với mỗi số điện thoại đã đăng ký của doanh nghiệp, API Đám mây hỗ trợ tối đa 80 tin nhắn mỗi giây (mps) theo mặc định và tối đa 1.000 mps khi tự động nâng cấp.

Thông lượng bao gồm cả tin nhắn đến và tin nhắn đi, cũng như mọi loại tin nhắn. Lưu ý rằng bất kể thông lượng, số điện thoại của doanh nghiệp vẫn phải tuân theo giới hạn tốc độ cho trường hợp sử dụng của doanh nghiệp và giới hạn nhắn tin theo mẫu của Tài khoản WhatsApp Business mà doanh nghiệp đó sở hữu.

Nếu bạn cố gửi nhiều tin nhắn hơn mức thông lượng hiện tại cho phép, API này sẽ trả về mã lỗi 130429 cho đến khi bạn giảm số lượng tin nhắn về mức cho phép. Mức thông lượng cũng được dùng cho những chiến dịch nhắn tin liên quan đến nhiều số điện thoại của người dùng WhatsApp. Nếu cố gửi quá nhiều tin nhắn đến một số điện thoại của người dùng WhatsApp, bạn có thể gặp lỗi giới hạn tốc độ ghép nối.

Tăng thông lượng

Nếu bạn đáp ứng yêu cầu về điều kiện, chúng tôi sẽ tự động nâng cấp số điện thoại của doanh nghiệp bạn lên 1.000 mps mà không mất phí. Việc tăng thông lượng không phát sinh thêm chi phí hay ảnh hưởng đến giá cả.

Bản thân quá trình nâng cấp có thể mất tối đa 1 phút. Trong thời gian này, số điện thoại nêu trên sẽ không sử dụng được trên nền tảng của chúng tôi. Nếu số này được sử dụng trong một yêu cầu API, API sẽ trả về mã lỗi 131057. Sau khi được nâng cấp, số điện thoại của doanh nghiệp sẽ tự động được nâng cấp nếu cần tăng thông lượng trong tương lai mà không có thời gian dừng chạy.

Yêu cầu về điều kiện

Webhooks

Máy chủ webhook của bạn phải có khả năng chịu được gấp 3 lần dung lượng lưu lượng tin nhắn đi và gấp 1 lần dung lượng lưu lượng tin nhắn đến dự kiến. Ví dụ: nếu gửi 1.000 mps với tỷ lệ phản hồi dự kiến là 30%, máy chủ của bạn phải có khả năng xử lý tối đa 3.000 webhook trạng thái tin nhắn cộng thêm 300 webhook tin nhắn đến.

Chúng tôi cố gắng phân phối webhook đồng thời, vì vậy, bạn nên đặt cấu hình và tải thử nghiệm máy chủ webhook của mình để xử lý các yêu cầu đồng thời theo tiêu chuẩn độ trễ dưới đây:

  • Độ trễ trung bình không vượt quá 250 mili giây.
  • Độ trễ dưới 1% vượt quá 1 giây.

Chúng tôi sẽ cố gắng phân phối lại các webhook bị lỗi trong tối đa 7 ngày, với khoảng thời gian chờ theo hàm mũ.

Tin nhắn có chứa file phương tiện

Để tận dụng tối đa thông lượng cao hơn, bạn nên tải tài sản file phương tiện lên máy chủ của chúng tôi và sử dụng ID file phương tiện được trả về trong tin nhắn có chứa file phương tiện thay vì lưu trữ tài sản trên máy chủ riêng của bạn và sử dụng URL của tài sản file phương tiện. Nếu muốn (hoặc phải) lưu trữ các tài sản đó trên máy chủ riêng, bạn nên sử dụng tính năng lưu file phương tiện vào bộ nhớ đệm.

Lấy mức thông lượng

Sử dụng điểm cuối Số điện thoại WhatsApp Business để lấy mức thông lượng hiện tại của một số điện thoại:

GET /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>?fields=throughput

Chuyển

Nếu bạn chuyển số điện thoại của doanh nghiệp có cài đặt đa kết nối đang chạy 2 đoạn trở lên từ API Tại chỗ sang API Đám mây, hệ thống sẽ tự động nâng cấp số điện thoại này lên thông lượng cao hơn.

Giới hạn tốc độ

Hãy xem phần Giới hạn tốc độ của WhatsApp Business Management API.

Ngoài những giới hạn tốc độ này, chúng tôi còn áp dụng giới hạn chi tiết hơn đối với từng tài nguyên, chẳng hạn như tin nhắn mẫu và số điện thoại thử nghiệm của doanh nghiệp:

Số liệu có sẵn

Là người dùng API Đám mây, bạn có thể xem số lượng tin nhắn đã gửi và phân phối, cũng như các số liệu khác. Hãy xem bài viết Lấy số liệu về tài khoản để biết thông tin.

Mở rộng quy mô

Trong cơ sở hạ tầng của Meta, API Đám mây sẽ tự động mở rộng quy mô và điều chỉnh để xử lý khối lượng công việc của bạn trong phạm vi giới hạn tốc độ (khối lượng nhắn tin và số lượng WABA).

Quyền riêng tư và bảo mật dữ liệu

Hãy xem phần Tổng quan về quyền riêng tư và bảo mật của chúng tôi để biết thông tin.

Mã hóa

Với API Đám mây, mọi tin nhắn WhatsApp vẫn sẽ được bảo vệ bằng phương thức mã hóa giao thức Signal để bảo mật tin nhắn trước khi gửi khỏi thiết bị. Nghĩa là tin nhắn qua WABA sẽ được phân phối một cách bảo mật đến nơi mà từng doanh nghiệp chọn.

API Đám mây sử dụng các kỹ thuật mã hóa theo tiêu chuẩn ngành để bảo vệ dữ liệu trong quá trình chuyển và ở trạng thái nghỉ. API này dùng API Đồ thị để gửi tin nhắn và dùng Webhooks để nhận sự kiện. Cả API Đồ thị và Webhooks đều hoạt động trên HTTPS theo tiêu chuẩn ngành, được bảo vệ bằng TLS. Hãy xem báo cáo nghiên cứu Tổng quan về mã hóa của chúng tôi để biết thêm chi tiết.

Hãy xem báo cáo nghiên cứu Tổng quan về mã hóa của chúng tôi để biết thêm chi tiết.

Giới hạn tốc độ ghép nối

Số điện thoại của doanh nghiệp chỉ có thể gửi 1 tin nhắn/6 giây đến cùng một số điện thoại của người dùng WhatsApp (0,17 tin nhắn/giây). Giới hạn này gần tương đương với 10 tin nhắn/phút hoặc 600 tin nhắn/giờ. Nếu bạn vượt quá giới hạn này, API sẽ trả về mã lỗi 131056 cho đến khi tốc độ của bạn lại nằm trong giới hạn.

Nếu cần thiết, bạn có thể gửi tối đa 45 tin nhắn trong vòng 6 giây dưới dạng một loạt tin nhắn. Nếu gửi một loạt tin nhắn, về cơ bản, bạn đang mượn thêm giới hạn tốc độ ghép nối. Do đó, bạn sẽ bị chặn gửi tin nhắn tiếp theo đến người dùng đó cho đến hết khoảng thời gian thông thường cần để gửi số lượng tin nhắn "riêng lẻ" tương đương đến người dùng nêu trên. Ví dụ: bạn cần khoảng 2 phút để gửi 20 tin nhắn "riêng lẻ" cho một người dùng. Vì vậy, nếu gửi một loạt 20 tin nhắn, bạn sẽ phải đợi khoảng 2 phút thì mới có thể gửi tin nhắn khác cho người dùng đó.

Để tránh phải tính thời gian chờ sau khi gửi một loạt tin nhắn, nếu yêu cầu gửi tin nhắn không thành công sau khi gửi một loạt tin nhắn, bạn nên thử lại sau 4^X giây, trong đó X = 0 và tăng thêm 1 sau mỗi lần thử thất bại, cho đến khi yêu cầu thành công.

Công cụ

Trình quản lý WhatsApp

Trình quản lý WhatsApp là ứng dụng web của chúng tôi, giúp bạn tự mình quản lý các tài nguyên trên WhatsApp (chẳng hạn như WABA, số điện thoại của doanh nghiệp và mẫu) và dễ dàng xem thông tin chi tiết cũng như xếp hạng chất lượng hoặc giới hạn đối với những tài nguyên này. Hầu hết các chức năng mà Trình quản lý WhatsApp cung cấp đều sử dụng được qua API, chỉ có một số ít trường hợp ngoại lệ.

Bạn có thể truy cập vào Trình quản lý WhatsApp theo nhiều cách. Mỗi cách đều giả định rằng bạn đã hoàn tất mọi bước trong tài liệu hướng dẫn Bắt đầu của chúng tôi.

Qua Meta Business Suite

  1. Đăng nhập vào Meta Business Suite.
  2. Nếu bạn có nhiều hồ sơ doanh nghiệp, hãy sử dụng menu thả xuống ở bên trái để chọn tài khoản sở hữu hoặc có quyền truy cập vào WABA mà bạn muốn tải trong Trình quản lý WhatsApp.
  3. Trong menu bên trái, chuyển đến Tài khoản > Tài khoản WhatsApp.
  4. Chọn WABA.
  5. Ở tab Tóm tắt, nhấp vào nút Trình quản lý WhatsApp.

Qua Bảng điều khiển ứng dụng

  1. Mở trang Ứng dụng của tôi.
  2. Chọn ứng dụng được liên kết với WABA mà bạn muốn tải trong Trình quản lý WhatsApp.
  3. Trong menu bên trái, chuyển đến WhatsApp > Bắt đầu nhanh.
  4. Nhấp vào lát Thông tin tài khoản trong phần WhatsApp Business.

Qua URL

Bạn có thể chuyển thẳng đến phần Tổng quan về Trình quản lý WhatsApp để xem tất cả WABA thuộc sở hữu của/được chia sẻ với một hồ sơ doanh nghiệp cụ thể, bằng cách truy cập vào:

https://business.facebook.com/wa/manage/home/

Theo mặc định, phần tổng quan này sẽ tải WABA gần đây nhất mà bạn tạo hoặc được cấp quyền truy cập. Tuy nhiên, bạn có thể sử dụng menu thả xuống ở bên trái để chọn hồ sơ doanh nghiệp có chứa WABA mà bạn đang cố truy cập. Khi đó, bạn sẽ thoát khỏi phần tổng quan, đồng thời phải sử dụng menu ở bên trái và chuyển đến Tài khoản > Tài khoản WhatsApp > (chọn WABA mong muốn) > Cài đặt > (nút) Trình quản lý WhatsApp.

Ngoài ra, nếu có nhiều hồ sơ doanh nghiệp, bạn có thể thêm ID của một tài khoản vào cuối URL rồi đánh dấu URL này để truy cập dễ dàng hơn:

https://business.facebook.com/wa/manage/home/?business_id=<META_BUSINESS_ACCOUNT_ID>

Postman

Chúng tôi cung cấp bộ sưu tập API Đám mây trên Postman chứa các truy vấn thường gặp trong không gian làm việc cho Nền tảng WhatsApp Business.