Nền tảng WhatsApp Business > API Đám mây > Hướng dẫn

Chuyển từ API Tại chỗ sang API Đám mây

Tài liệu này giải thích cách chuyển số điện thoại của doanh nghiệp từ API Tại chỗ sang API Đám mây.

Lưu ý rằng quy trình chuyển số điện thoại của doanh nghiệp giữa các API không giống với quy trình chuyển số điện thoại giữa các Tài khoản WhatsApp Business (WABA).

Để chuyển từ API Đám mây sang API Tại chỗ, hãy xem bài viết Chuyển từ API Đám mây sang API Tại chỗ.

Cách hoạt động

Quá trình chuyển liên quan đến việc tạo siêu dữ liệu về số điện thoại của doanh nghiệp, rồi dùng dữ liệu này để đăng ký sử dụng số điện thoại đó với API Đám mây. Việc này sẽ hủy đăng ký số điện thoại đó khỏi API Tại chỗ vì bạn chỉ có thể đăng ký một số điện thoại để sử dụng với một API mỗi lúc.

Quy trình chuyển KHÔNG ảnh hưởng đến:

tên hiển thị, trạng thái xác minh hoặc xếp hạng chất lượng của số điện thoại của doanh nghiệp
các mẫu mà số điện thoại của doanh nghiệp sử dụng hoặc trạng thái của chúng
WABA sở hữu, trạng thái Tài khoản kinh doanh chính thức hoặc giới hạn nhắn tin của tài khoản đó

Tuy nhiên, để hỗ trợ quá trình chuyển, bạn phải nắm rõ điểm khác biệt giữa các API và có hành động thích hợp để giải quyết trước khi thực hiện các bước chuyển như đã nêu trong tài liệu này.

Yêu cầu

Ứng dụng trên Meta

Bạn phải có một ứng dụng kinh doanh trên Meta có thể sử dụng API Đám mây và API Quản lý doanh nghiệp đã tích hợp dữ liệu của khách hàng, đồng thời có thể xử lý các webhook của API Đám mây và API Quản lý doanh nghiệp. Ngoài ra, ứng dụng đó phải được liên kết với/xác nhận bởi Tài khoản kinh doanh trên Meta đã xác minh của bạn.

Nếu bạn không có ứng dụng kinh doanh trên Meta hoặc nếu ứng dụng của bạn chưa được đặt cấu hình sản phẩm WhatsApp, hãy hoàn thành các bước trong hướng dẫn Bắt đầu sử dụng API Đám mây của chúng tôi. Sau khi hoàn thành các bước này, hệ thống sẽ tạo tất cả tài sản cần thiết để thử nghiệm API Đám mây và API Quản lý doanh nghiệp.

Xét duyệt ứng dụng

Ứng dụng trên Meta của bạn phải trải qua quy trình Xét duyệt ứng dụng và được phê duyệt (tức là có quyền truy cập nâng cao) đối với các quyền whatsapp_business_messaging và whatsapp_business_management.

Cách làm tốt nhất

Sau khi đảm bảo rằng ứng dụng đó có thể xử lý tất cả những điểm khác biệt về API, trước tiên, bạn nên chuyển số điện thoại của doanh nghiệp có số lượng hoạt động nhỏ và xác minh rằng tất cả chức năng mà bạn định cung cấp với API Đám mây đều hoạt động chính xác. Sau khi xác minh rằng mọi thứ đều hoạt động bình thường, hãy chuyển các số điện thoại khác.

Bạn cũng nên chuyển khi lưu lượng truy cập vào phương thức triển khai API Tại chỗ ở mức thấp.

Điểm khác biệt giữa các API

API Đám mây không hỗ trợ hoặc có phương thức xử lý khác đối với các tính năng dưới đây của API Tại chỗ. Hãy đảm bảo ứng dụng của bạn có thể xử lý những điểm khác biệt này trước khi bắt đầu quá trình chuyển.

Webhooks

Phần tải dữ liệu webhook của API Đám mây và API Quản lý doanh nghiệp có cấu trúc khác với phần tải dữ liệu của API Tại chỗ. Bạn nên tạo một điểm cuối webhook mới có thể xử lý riêng API Đám mây và API Quản lý doanh nghiệp.

Hãy tham khảo các tài liệu sau để hiểu rõ điểm khác biệt về phần tải dữ liệu và cách đặt cấu hình webhook trên ứng dụng của bạn thông qua Bảng điều khiển ứng dụng:

Cấu hình: Webhooks cho WhatsApp
Phần tải dữ liệu webhook của API Đám mây: Tài liệu tham khảo về phần tải dữ liệu của thông báo webhook
Phần tải dữ liệu webhook của API Quản lý doanh nghiệp: Thiết lập webhook

Lưu ý rằng sau khi chuyển số điện thoại của doanh nghiệp sang API Đám mây, bạn phải sử dụng điểm cuối Tài khoản WhatsApp Business > Ứng dụng đã đăng ký để đăng ký webhook cho ứng dụng trên Meta của bạn trên WABA được liên kết với số điện thoại của doanh nghiệp đó:

Cú pháp yêu cầu

curl -X POST 'https://graph.facebook.com/v17.0/<WABA_ID>/subscribed_apps' \
-H 'Authorization: Bearer EAAJB...'

Sau khi quá trình chuyển sang API Đám mây hoàn tất, webhook API Tại chỗ của số điện thoại của doanh nghiệp này sẽ không được phân phối nữa và quá trình phân phối webhook API Đám mây sẽ bắt đầu.

File phương tiện

Do không thể sử dụng ID file phương tiện của bất kỳ file phương tiện nào được tải lên API Tại chỗ khi gửi tin nhắn bằng API Đám mây, bạn phải tải lại file phương tiện lên bằng API Đám mây để tạo ID file phương tiện mới hoặc sử dụng URL file phương tiện nếu file phương tiện đó được lưu trữ trên máy chủ công khai. Hãy xem phần Tin nhắn có chứa file phương tiện và Mẫu tin nhắn dạng file phương tiện.

Lưu ý rằng để đảm bảo tính toàn vẹn của tin nhắn, API Đám mây không cho phép một số miền lưu trữ file phương tiện mà API Tại chỗ cho phép. Nếu sử dụng một dịch vụ lưu trữ cho file phương tiện, bạn nên thử nghiệm URL file phương tiện trong tin nhắn dạng tự do và tin nhắn mẫu trước khi chuyển. Nếu bạn cho rằng máy chủ của mình bị chặn do nhầm lẫn, vui lòng liên hệ với bộ phận hỗ trợ.

Mã lỗi

Mã lỗi của API Đám mây và API Quản lý doanh nghiệp khác với mã lỗi của API Tại chỗ. Hãy xem tài liệu dưới đây:

Xác thực thuộc tính

API Tại chỗ có thể chấp nhận các thuộc tính không xác định trong phần tải dữ liệu của nội dung yêu cầu POST cho tin nhắn, nhưng API Đám mây sẽ từ chối những yêu cầu này. Vì vậy, hãy đảm bảo yêu cầu gửi tin nhắn của bạn chỉ sử dụng các thuộc tính được hỗ trợ.
API Tại chỗ cho phép bỏ qua chỉ mục nút khi gửi tin nhắn chỉ có một nút, nhưng API Đám mây sẽ từ chối những yêu cầu này. Vì vậy, hãy đảm bảo các yêu cầu gửi tin nhắn có chứa nút cũng bao gồm các chỉ mục và giá trị của chúng.
API Tại chỗ chấp nhận chuỗi văn bản chứa khoảng trắng ở đầu hoặc cuối (hoặc chỉ chứa khoảng trắng) trên thuộc tính đối tượng hành động và nút khi gửi tin nhắn tương tác, nhưng API Đám mây sẽ từ chối những yêu cầu này.

Tin nhắn nhấn để nói

API Tại chỗ xác định tin nhắn nhấn để nói (PTT) trong webhook bằng cách đặt messages.type thành voice, nhưng API Đám mây xác định tin nhắn PTT bằng cách đặt messages.audio.voice thành true.

Gói nhãn dán

API Đám mây không hỗ trợ gói nhãn dán.

Thời gian dừng chạy

Thời gian dừng chạy bắt đầu ngay khi bạn thực hiện bước chuyển cuối cùng (đăng ký số điện thoại để sử dụng với API Đám mây) và sẽ chỉ kéo dài vài giây. Trong thời gian này, hệ thống sẽ tự động hủy bỏ tin nhắn mà người dùng WhatsApp gửi đến số điện thoại đó.

Bạn nên đặt lịch chuyển trong thời gian số điện thoại có ít hoạt động để giảm thiểu bất kỳ tác động nào do thời gian dừng chạy gây ra.

Thông lượng

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

Tài khoản kinh doanh chính thức

Nếu bạn đang chuyển một số điện thoại của doanh nghiệp có trạng thái Tài khoản kinh doanh chính thức (OBA) , hệ thống sẽ giữ nguyên trạng thái như vậy nếu bạn thêm siêu dữ liệu của số đó (được tạo ở bước 2) khi đăng ký số (bước 3). Nếu bạn bỏ qua dữ liệu này, số ở trên sẽ mất trạng thái OBA.

Hỗ trợ chuyển

Nếu bạn có thắc mắc hoặc cần trợ giúp trong quá trình chuyển, hãy gửi phiếu yêu cầu Hỗ trợ trực tiếp với:

Chủ đề: WABiz: API Đám mây
Loại yêu cầu: Vấn đề khi chuyển từ API Tại chỗ -> API Đám mây

Bước 1: Vô hiệu hóa tính năng xác minh hai bước

Nếu biết mã PIN cho số điện thoại của doanh nghiệp, bạn có thể bỏ qua bước này.

Bạn sẽ cần mã PIN cho số điện thoại của doanh nghiệp khi thực hiện bước 3. Vì vậy, nếu không biết mã PIN, trước tiên, bạn phải vô hiệu hóa tính năng xác minh hai bước trên số điện thoại của doanh nghiệp này. Nếu bạn không sở hữu số điện thoại của doanh nghiệp, hãy yêu cầu chủ sở hữu vô hiệu hóa tính năng này.

Bước 2: Tạo siêu dữ liệu về số điện thoại

Sử dụng API Sao lưu và khôi phục để tạo siêu dữ liệu về số điện thoại của doanh nghiệp.

Cú pháp yêu cầu

POST /v1/settings/backup
{
  "password": "<PASSWORD>"
}

<PASSWORD> có thể là một chuỗi bất kỳ. Giá trị này sẽ được dùng để mã hóa siêu dữ liệu. Vì vậy, hãy theo dõi giá trị này để sử dụng trong bước tiếp theo.

Phản hồi

{
  "settings": {
    "data": "<METADATA>"
  },
  "meta": {
    "api_status": "<API_STATUS>",
    "version": "<API_VERSION>"
  }
}

API sẽ trả về chuỗi mã hóa được chỉ định cho thuộc tính data mô tả số điện thoại của doanh nghiệp và cài đặt của số đó. Hãy ghi lại giá trị này để sử dụng trong bước tiếp theo.

<METADATA> - Đây là chuỗi mã hóa mô tả số điện thoại của doanh nghiệp và cài đặt của số đó. Hãy ghi lại giá trị này để sử dụng trong bước tiếp theo.
<API_STATUS> - Trạng thái của phương thức triển khai API Tại chỗ.
<API_VERSION> - Số phiên bản của API Tại chỗ mà bạn đang chạy.

Yêu cầu mẫu

curl 'https://localhost:9090/v1/settings/backup' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "password": "tacocat"
}'

Phản hồi mẫu

{
  "settings": {
    "data": "V0FCS..."
  },
  "meta": {
    "api_status": "stable",
    "version": "2.49.3"
  }
}

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

Sử dụng điểm cuối Số điện thoại WhatsApp Business > Đăng ký trên API Đám mây khi đăng ký số điện thoại để sử dụng với API Đám mây.

Thêm giá trị siêu dữ liệu về số điện thoại của doanh nghiệp được mã hóa và mật khẩu từ bước trước đó. Bạn có thể đăng ký số điện thoại mà không cần dữ liệu này. Tuy nhiên, nếu không đưa dữ liệu này vào, dữ liệu trang cá nhân cho số điện thoại của doanh nghiệp sẽ bị mất và có thể ảnh hưởng đến trạng thái Tài khoản kinh doanh chính thức của Tài khoản WhatsApp Business.

Cú pháp yêu cầu

POST /<BUSINESS_PHONE_NUMBER_ID>/register

Nội dung yêu cầu POST

{
  "messaging_product": "whatsapp",
  "pin": "<NEW_OR_EXISTING_PIN>",
  "backup": {
    "password": "<PASSWORD>",
    "data": "<METADATA>"
  }
}

<NEW_OR_EXISTING_PIN> - Mã PIN hiện có hoặc mã PIN bạn muốn đặt trên số điện thoại của doanh nghiệp.
<PASSWORD> - Mật khẩu bạn đã dùng để tạo siêu dữ liệu cho số điện thoại của doanh nghiệp ở bước trước đó.
<METADATA> - Chuỗi mã hóa mô tả số điện thoại của doanh nghiệp và cài đặt của số đó, được tạo ở bước trước đó.

Phản hồi

{
  "success": <SUCCESS>
}

API sẽ trả về success được đặt là true nếu đăng ký thành công hoặc false nếu xảy ra lỗi.

Yêu cầu mẫu

curl 'https://graph.facebook.com/v19.0/110200345501442/register' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "messaging_product": "whatsapp",
  "pin": "134568",
  "backup": {
    "password": "tacocat",
    "data": "V0FCS..."
  }
}'

Phản hồi mẫu

{
  "success": true
}

Bước 4: Kiểm tra trạng thái tình trạng nhắn tin (không bắt buộc)

Yêu cầu trường health_status trên số điện thoại của doanh nghiệp và xác minh rằng trường này có thể được dùng để nhắn tin thông qua API Đám mây. Hãy xem bài viết Trạng thái tình trạng nhắn tin.

Nền tảng WhatsApp Business | API Đám mây | API Quản lý doanh nghiệp