Bắt đầu dành cho BSP

Bắt đầu dành cho Nhà cung cấp giải pháp kinh doanh

Hướng dẫn này trình bày các bước mà Nhà cung cấp giải pháp kinh doanh (BSP) cần thực hiện để cung cấp API Đám mây cho khách hàng của họ. Có 4 giai đoạn chính:

1. Chuẩn bị và lên kế hoạch

2. Thiết lập tài sản

3. Ký hợp đồng

4. Xây dựng tiện ích tích hợp

Sau khi bạn hoàn tất, vui lòng theo dõi bản cập nhật hàng tháng.

Chuẩn bị và lên kế hoạch

Đọc tài liệu

Trước khi bắt đầu, bạn nên đọc qua tài liệu dành cho nhà phát triển và bộ sưu tập Postman của chúng tôi. Qua đó, bạn có thể nắm được cách hoạt động của API Đám mây - bao gồm cả cách bắt đầu sử dụng và chuyển số.

Lên kế hoạch tích hợp và chuyển

Bạn phải sử dụng quy trình Đăng ký nhúng để tích hợp khách hàng mới với API Đám mây. Nếu bạn chưa tích hợp, hãy tích hợp và khởi chạy quy trình Đăng ký nhúng. Quy trình Đăng ký nhúng là cách nhanh nhất và dễ nhất để đăng ký khách hàng, cho phép khách hàng bắt đầu gửi tin nhắn trong vòng chưa đầy 5 phút.

Tiếp theo, hãy nghĩ về những khách hàng mà bạn muốn chuyển sang API Đám mây trước tiên. Nhìn chung, bạn nên chuyển tất cả khách hàng từ API Tại chỗ sang API Đám mây, nhưng nhu cầu của mỗi khách hàng có thể khác nhau. Khi nghĩ về những khách hàng cần chuyển, bạn nên cân nhắc những điều sau đây:

Cân nhắc	Ngữ cảnh bổ sung
API Đám mây có hỗ trợ thông lượng và khối lượng tin nhắn của khách hàng không?	API Đám mây hỗ trợ thông lượng tích lũy cao nhất là 250 tin nhắn/giây cho hầu hết các doanh nghiệp, bao gồm cả tin nhắn văn bản/tin nhắn có chứa file phương tiện và tin nhắn đến/đi.
API Đám mây có đáp ứng nhu cầu tuân thủ của khách hàng không?	API Đám mây tuân thủ GDPR và có chứng nhận SOC 2. Các máy chủ được lưu trữ ở Bắc Mỹ và châu Âu.
Khách hàng của tôi có đang sử dụng các tính năng mà API Đám mây hỗ trợ không?	Hầu hết các tính năng chính đều được hỗ trợ. Hãy xem danh sách đầy đủ tại đây.

Sau khi biết được những người sẽ được chuyển, bạn có thể lên kế hoạch và lịch trình chuyển.

Khi bạn lên kế hoạch, hãy nhớ thiết kế hệ thống cho 2 trường hợp: tích hợp khách hàng mới và chuyển khách hàng hiện tại từ API Tại chỗ sang API Đám mây. Đối với trường hợp chuyển, bạn hãy lên kế hoạch sao lưu phiên bản Tại chỗ hiện tại và chuyển những số đó sang API Đám mây.

Lên kế hoạch thông báo cho khách hàng

Trước tiên, bạn cần xác định xem có thông báo cho khách hàng hiện tại về kế hoạch chuyển hay không. Sau đó, bạn nên xác định xem mình có cần tạo hay cập nhật tài liệu nào để hỗ trợ thiết lập API Đám mây hay không.

Đưa ra quyết định về giá

Chi phí lưu trữ của API Đám mây do Meta chi trả, vì vậy, bạn nên xác định xem mình có muốn cập nhật giá cho phù hợp hay không.

Thiết lập tài sản

Để sử dụng API Đám mây, BSP cần có những tài sản sau đây:

Tài sản	Hướng dẫn cụ thể
Trình quản lý kinh doanh	Bạn có thể sử dụng Trình quản lý hiện có hoặc thiết lập Trình quản lý mới. Lưu ID Trình quản lý kinh doanh.
Tài khoản WhatsApp Business (WABA)	Hãy xem phần Tạo Tài khoản WhatsApp Business cho API WhatsApp Business để được trợ giúp.
Ứng dụng trên Meta	Nếu chưa có ứng dụng, bạn cần tạo một ứng dụng thuộc loại "Kinh doanh". Hãy nhớ thêm tên hiển thị và email liên hệ vào ứng dụng của bạn. Với vai trò BSP (Nhà cung cấp giải pháp kinh doanh), ứng dụng của bạn phải trải qua quy trình Xét duyệt ứng dụng và yêu cầu Quyền truy cập nâng cao cho những quyền sau đây: whatsapp_business_management - Dùng để quản lý số điện thoại, mẫu tin nhắn, đăng ký, trang kinh doanh trong một Tài khoản WhatsApp Business. Ứng dụng của bạn phải trải qua quy trình Xét duyệt ứng dụng thì mới nhận được quyền này. whatsapp_business_messaging - Dùng để gửi/nhận tin nhắn từ người dùng WhatsApp, tải lên/tải xuống file phương tiện trong Tài khoản WhatsApp Business. Ứng dụng của bạn phải trải qua quy trình Xét duyệt ứng dụng thì mới nhận được quyền này. business_management Xem ví dụ về trường hợp gửi đi Xét duyệt ứng dụng tại đây. Là BSP, bạn cũng có thể dùng cùng một ứng dụng trên Meta cho nhiều khách hàng và WABA. Tuy nhiên, cần lưu ý rằng mỗi ứng dụng chỉ được có một điểm cuối webhook và mọi ứng dụng đều cần phải trải qua quy trình Xét duyệt ứng dụng.
Người dùng hệ thống	Hãy xem phần Thêm người dùng hệ thống vào Trình quản lý kinh doanh để được trợ giúp. Hiện tại, Ứng dụng trên Meta có các quyền whatsapp_business_messaging, whatsapp_business_management và business_messaging sẽ có quyền truy cập tối đa: 1 người dùng hệ thống là quản trị viên và 1 người dùng hệ thống là nhân viên Bạn nên sử dụng người dùng hệ thống là quản trị viên khi triển khai chính thức. Hãy xem phần Giới thiệu về vai trò và quyền trong Trình quản lý kinh doanh để biết thêm thông tin.
Số điện thoại của doanh nghiệp	Đây là số điện thoại mà doanh nghiệp sẽ dùng để gửi tin nhắn. Bạn cần xác minh số điện thoại qua SMS/cuộc gọi thoại. Đối với BSP và Doanh nghiệp trực tiếp: Nếu muốn sử dụng số điện thoại của mình, bạn có thể thêm số điện thoại vào Trình quản lý WhatsApp và xác minh với điểm cuối xác minh qua API Đồ thị. Đối với Doanh nghiệp sử dụng BSP: Nếu muốn sử dụng số điện thoại của mình, bạn cần thêm và xác minh số điện thoại qua quy trình Đăng ký nhúng của BSP. Trạng thái xác minh của số điện thoại không ảnh hưởng đến khả năng chuyển giữa API Tại chỗ và API đám mây. Nếu không có quyền truy cập quy trình Đăng ký nhúng để xác minh số điện thoại, bạn nên xác minh số điện thoại bằng giải pháp Tại chỗ, sau đó chuyển số điện thoại đó sang API Đám mây. Không có giới hạn về số lượng số điện thoại của doanh nghiệp được phép tích hợp với API Đám mây. Mỗi lúc bạn chỉ có thể dùng một số điện thoại trên một nền tảng: Một số điện thoại cho API Đám mây và một số khác cho API Tại chỗ. Nghĩa là bạn không được sử dụng một số điện thoại chính thức cho cả API Đám mây và API Tại chỗ. Bạn nên thực hiện mọi thử nghiệm bằng số điện thoại thử nghiệm (số thử nghiệm có sẵn hoặc số mới), sau đó chuyển số điện thoại của bạn sang API Đám mây khi đã sẵn sàng sử dụng chính thức.
Số điện thoại của người tiêu dùng	Đây là số điện thoại đang dùng ứng dụng WhatsApp dành cho người tiêu dùng. Số điện thoại này sẽ nhận tin nhắn được gửi từ số điện thoại của doanh nghiệp.

Ký hợp đồng

Chấp nhận Điều khoản dịch vụ

Để truy cập API Đám mây nhắn tin đến WhatsApp Business, đầu tiên, bạn cần chấp nhận Điều khoản dịch vụ của Nền tảng WhatsApp Business thay mặt cho doanh nghiệp.

Để thực hiện việc này, hãy chuyển đến Trình quản lý WhatsApp và chấp nhận các điều khoản dịch vụ trong biểu ngữ thông tin.

Nếu đang là đối tác sử dụng bản beta của API Đám mây, bạn sẽ có khoảng thời gian gia hạn là 90 ngày. Nghĩa là bạn cần chấp nhận các điều khoản trước ngày 05/07/2022 để không bị mất quyền truy cập.

Đối với các doanh nghiệp mới sử dụng API Đám mây, kể cả doanh nghiệp chuyển từ API tại chỗ sang API Đám mây, bạn sẽ cần chấp nhận các điều khoản dịch vụ trước khi có thể bắt đầu sử dụng API Đám mây. Lệnh gọi đăng ký sẽ không thành công cho đến khi bạn chấp nhận các điều khoản dịch vụ.

Nhà phát triển cần chấp nhận các điều khoản dịch vụ. Nếu bạn là Nhà cung cấp giải pháp kinh doanh, khách hàng của bạn sẽ không cần chấp nhận các điều khoản dịch vụ.

Xây dựng tiện ích tích hợp

Bước 1: Lấy mã truy cập dành cho người dùng hệ thống

Lệnh gọi API Đồ thị dùng mã truy cập để xác thực. Để biết thêm thông tin, hãy xem phần Mã truy cập. Bạn nên sử dụng người dùng hệ thống để tạo mã truy cập.

Cách tạo mã truy cập dành cho người dùng hệ thống:

1. Chuyển đến Trình quản lý kinh doanh > Cài đặt cho doanh nghiệp > Người dùng > Người dùng hệ thống để xem người dùng hệ thống mà bạn đã tạo.

2. Nhấp vào người dùng đó rồi chọn Thêm tài sản. Hành động này sẽ mở ra cửa sổ mới.

3. Trong phần Chọn loại tài sản ở bảng điều khiển bên trái, hãy chọn Ứng dụng. Trong phần Chọn tài sản, hãy chọn ứng dụng trên Meta mà bạn muốn sử dụng (ứng dụng của bạn phải có các quyền phù hợp). Bật quyền Phát triển ứng dụng cho ứng dụng đó.

4. Chọn Lưu thay đổi để lưu cài đặt và quay lại màn hình chính của người dùng hệ thống.

5. Bây giờ, bạn đã sẵn sàng tạo mã truy cập. Trên màn hình chính của người dùng hệ thống, hãy nhấp vào Tạo mã rồi chọn ứng dụng của bạn trên Meta. Sau khi chọn ứng dụng, bạn sẽ thấy danh sách các quyền có sẵn. Chọn whatsapp_business_management, whatsapp_business_messaging và business_management. Nhấp vào Tạo mã.

6. Cửa sổ mới mở ra hiển thị thông tin người dùng hệ thống, ứng dụng được chỉ định và mã truy cập. Lưu mã truy cập.

7. Nếu muốn, bạn có thể nhấp vào mã truy cập và xem Trình gỡ lỗi mã truy cập. Trong trình gỡ lỗi, bạn sẽ nhìn thấy 2 quyền mà mình đã chọn. Bạn cũng có thể dán trực tiếp mã truy cập vào Trình gỡ lỗi mã truy cập.

Bước 2: Thiết lập Webhooks

Với Webhooks được thiết lập, bạn có thể nhận thông báo HTTP theo thời gian thực từ Nền tảng WhatsApp Business. Nghĩa là bạn sẽ nhận được thông báo khi nhận được tin nhắn từ khách hàng hoặc khi Tài khoản WhatsApp Business (WABA) có thay đổi.

Để thiết lập Webhook, bạn cần tạo một máy chủ web kết nối Internet có URL đáp ứng yêu cầu của Meta và WhatsApp. Hãy xem phần Tạo điểm cuối để được hướng dẫn cách thực hiện. Nếu cần điểm cuối cho mục đích thử nghiệm, bạn có thể tạo điểm cuối Webhooks thử nghiệm.

Thiết lập ứng dụng

Sau khi điểm cuối đã sẵn sàng, hãy đặt cấu hình điểm cuối để ứng dụng trên Meta sử dụng:

Trong Bảng điều khiển ứng dụng của bạn, hãy tìm sản phẩm WhatsApp rồi nhấp vào Cấu hình. Sau đó, tìm phần webhooks rồi nhấp vào Đặt cấu hình webhook. Sau khi bạn nhấp vào, một hộp thoại sẽ xuất hiện trên màn hình và yêu cầu bạn cung cấp 2 mục sau:

• URL gọi lại: Đây là URL mà Meta sẽ gửi sự kiện đến. Hãy xem hướng dẫn Bắt đầu trong phần Webhooks để biết thông tin về cách tạo URL này.

• Mã xác minh: Chuỗi này do bạn thiết lập khi tạo điểm cuối webhook của mình.

Sau khi bạn thêm thông tin này, hãy nhấp vào Xác minh và lưu.

Tiếp theo, quay lại Bảng điều khiển ứng dụng, nhấp vào WhatsApp > Cấu hình trong bảng điều khiển phía bên trái. Bên dưới phần Webhooks, hãy nhấp vào Quản lý. Một hộp thoại sẽ mở ra cùng với tất cả các đối tượng bạn có thể nhận được thông báo. Nếu bạn muốn nhận tin nhắn từ người dùng, hãy nhấp vào Đăng ký nhận tin nhắn.

Bạn chỉ cần thiết lập Webhooks một lần cho mọi ứng dụng của mình. Bạn có thể dùng cùng một Webhook để nhận nhiều loại sự kiện từ nhiều Tài khoản WhatsApp Business. Để biết thêm thông tin, hãy xem phần Webhooks.

Hiện tại, mỗi Ứng dụng trên Meta chỉ có thể yêu cầu đặt cấu hình một điểm cuối. Nếu cần gửi bản cập nhật webhook đến nhiều điểm cuối, bạn cần có nhiều Ứng dụng trên Meta.

Bước 3: Đăng ký với WABA

Để đảm bảo bạn nhận được thông báo cho đúng tài khoản, hãy đăng ký ứng dụng của mình:

curl -X POST \
'https://graph.facebook.com/v17.0/WHATSAPP_BUSINESS_ACCOUNT_ID/subscribed_apps' \
-H 'Authorization: Bearer ACCESS_TOKEN'

Nếu bạn nhận được phản hồi dưới đây, tất cả các sự kiện Webhook cho số điện thoại trong tài khoản này sẽ được gửi đến điểm cuối Webhooks mà bạn đã đặt cấu hình.

{
  "success": true
}

Bước 4: Lấy ID số điện thoại

Để gửi tin nhắn, bạn cần đăng ký số điện thoại sẽ sử dụng - đây là số điện thoại của doanh nghiệp mà chúng tôi đã đề cập trong phần Trước khi bạn bắt đầu.

Trước khi tiếp tục đăng ký, bạn cần tìm ID của số điện thoại đó. Để lấy ID của số điện thoại, hãy thực hiện lệnh gọi API sau đây:

curl -X GET \
'https://graph.facebook.com/v17.0/WHATSAPP_BUSINESS_ACCOUNT_ID/phone_numbers' \
-H 'Authorization: Bearer ACCESS_TOKEN'

Nếu yêu cầu thành công, phản hồi sẽ bao gồm tất cả những số điện thoại được liên kết với WABA của bạn:

{
  "data": [
    {
      "verified_name": "Jasper's Market",
      "display_phone_number": "[phone]",
      "id": "1906385232743451",
      "quality_rating": "GREEN"
    },
    {
      "verified_name": "Jasper's Ice Cream",
      "display_phone_number": "[phone]",
      "id": "1913623884432103",
      "quality_rating": "NA"
    }
  ]
}

Lưu ID của số điện thoại mà bạn muốn đăng ký. Hãy xem phần Đọc số điện thoại để biết thêm thông tin về điểm cuối này.

Ngoại lệ khi chuyển

Nếu đang chuyển một số điện thoại từ API Tại chỗ sang API Đám mây, bạn cần thực hiện thêm một số bước trước khi đăng ký số điện thoại với API Đám mây. Hãy xem phần Chuyển giữa API Tại chỗ và API Đám mây để biết quy trình đầy đủ.

Bước 5: Đăng ký số điện thoại

Sau khi có ID, bạn có thể đăng ký số điện thoại. Trong lệnh gọi API đăng ký, bạn có thể thực hiện 2 hành động cùng lúc:

1. Đăng ký số điện thoại.

2. Bật xác minh 2 bước bằng cách đặt mã đăng ký gồm 6 chữ số - bạn phải đặt mã này ở phía mình. Lưu và ghi nhớ mã này vì bạn có thể cần dùng sau đó.

Bạn cần thiết lập tính năng xác thực 2 yếu tố để sử dụng API Đám mây. Nếu không thiết lập tính năng này, bạn sẽ nhận được thông báo lỗi tích hợp:

Yêu cầu mẫu:

curl -X POST \
'https://graph.facebook.com/v17.0/FROM_PHONE_NUMBER_ID/register' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{"messaging_product": "whatsapp","pin": "6_DIGIT_PIN"}'

Phản hồi mẫu:

{
  "success": true
}

Người dùng quy trình Đăng ký nhúng

Bạn phải đăng ký số điện thoại trong vòng 14 ngày sau khi trải qua quy trình Đăng ký nhúng. Nếu không được đăng ký trong khoảng thời gian đó, số điện thoại sẽ phải trải qua quy trình Đăng ký nhúng lần nữa trước khi đăng ký.

Bước 6: Nhận tin nhắn từ ứng dụng dành cho người tiêu dùng

Sau khi khách hàng tham gia gửi tin nhắn đến doanh nghiệp, bạn sẽ có 24 giờ nhắn tin miễn phí với khách hàng - khoảng thời gian đó được gọi là khoảng thời gian dịch vụ khách hàng. Với mục đích thử nghiệm, chúng tôi muốn bật khoảng thời gian này để bạn có thể gửi số lượng tin nhắn tùy ý.

Từ ứng dụng WhatsApp cá nhân dành cho iOS/Android, hãy gửi tin nhắn đến số điện thoại bạn vừa đăng ký. Sau khi gửi được tin nhắn, bạn sẽ nhận được tin nhắn đến trong Webhook kèm theo thông báo ở định dạng sau đây.

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "WHATSAPP_BUSINESS_ACCOUNT_ID",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "16315551234",
              "phone_number_id": "PHONE_NUMBER_ID"
            },
            "contacts": [
              {
                "profile": {
                  "name": "Kerry Fisher"
                },
                "wa_id": "16315555555"
              }
            ],
            "messages": [
              {
                "from": "16315555555",
                "id": "wamid.ABGGFlA5FpafAgo6tHcNmNjXmuSf",
                "timestamp": "1602139392",
                "text": {
                  "body": "Hello!"
                },
                "type": "text"
                }
            ]
          },
        "field": "messages"
        }
      ]
    }
  ]
}

Bước 7: Gửi tin nhắn thử nghiệm

Sau khi bật khoảng thời gian dịch vụ khách hàng, bạn có thể gửi tin nhắn thử nghiệm đến số điện thoại của người tiêu dùng mà bạn sử dụng trong bước trước đó. Để làm điều đó, hãy thực hiện lệnh gọi API sau đây:

curl -X  POST \
'https://graph.facebook.com/v17.0/FROM_PHONE_NUMBER_ID/messages' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{"messaging_product": "whatsapp", "to": "16315555555","text": {"body" : "hello world!"}}'

Nếu lệnh gọi thành công, phản hồi sẽ chứa ID tin nhắn. Hãy dùng ID đó để theo dõi tiến độ của tin nhắn thông qua Webhooks. Độ dài tối đa của ID là 128 ký tự.

Phản hồi mẫu:

{
  "id":"wamid.gBGGFlaCGg0xcvAdgmZ9plHrf2Mh-o"
}

Với API Đám mây, bạn không có cách nào để kiểm tra rõ ràng xem một số điện thoại có ID WhatsApp hay không. Để gửi tin nhắn cho ai đó qua API Đám mây, bạn chỉ cần gửi trực tiếp đến số điện thoại của khách hàng – sau khi khách hàng đã chọn tham gia. Hãy xem ví dụ trong Tài liệu tham khảo, Tin nhắn.

Theo dõi bản cập nhật hàng tháng

Chúng tôi sẽ phát hành các bản cập nhật của API Đám mây vào thứ Ba đầu tiên hàng tháng. Những bản cập nhật đó sẽ bao gồm các tính năng và điểm cải tiến mới. Bạn không cần làm gì để sử dụng bất kỳ tính năng mới nào vì API Đám mây sẽ tự động cập nhật.

Câu hỏi thường gặp

Câu hỏi thường gặp chung

Which company will be providing the Cloud API?Are there any additional costs for the Cloud API?How can a Business Solutions Provider decide whether a given client should use the On-Premises or Cloud API? Do clients get a choice?Will consumers know whether a business is using the Cloud API or the On-Premises API?Will all features from the On-Premises API be available on the Cloud API?Does the introduction of Cloud API mean WhatsApp is deprecating the existing On-Premises API?

Câu hỏi thường gặp về hoạt động triển khai kỹ thuật

What is the architecture of the Cloud API?Will the BSP/direct client need containers and what data will be in those containers?What will disaster recovery look like: if a region is unavailable, how much time does it take to move messages to another region?How does WhatsApp recommend I conduct load tests for the Cloud API?

Câu hỏi thường gặp về quyền riêng tư và bảo mật dữ liệu

Where are the servers for the Cloud API?Is the Cloud API end-to-end encrypted? What is the encryption model?What happens to message data at rest? How is it handled? How long is it stored?Does Meta have access to encryption keys?

Câu hỏi thường gặp về việc tuân thủ quy định

Will the Cloud API be compliant with regional data protection laws (such as GDPR, LGPD, and PDPB)?