Số điện thoại xác minh trước

Tài liệu này giải thích cách cung cấp cho khách hàng cuối số điện thoại xác minh trước của doanh nghiệp trong quy trình Đăng ký nhúng sẵn mới. Số điện thoại xác minh trước của doanh nghiệp là số điện thoại của doanh nghiệp mà bạn đã xác minh nhằm giúp khách hàng cuối không cần phải liên hệ với bạn để yêu cầu mật khẩu một lần.

Lưu ý rằng số điện thoại xác minh trước của doanh nghiệp được biểu thị bằng đối tượng Số điện thoại xác minh trước cho WhatsApp Business. Đây là các đối tượng tạm thời. Khi khách hàng cuối chọn một trong những số điện thoại này và hoàn tất quy trình Đăng ký nhúng sẵn mới, đối tượng tạm thời đó sẽ được thay thế bằng đối tượng Số điện thoại WhatsApp Business và bạn phải lấy ID của đối tượng mới để đăng ký số điện thoại.

Yêu cầu

• Doanh nghiệp của bạn phải là Đối tác giải pháp đã được phê duyệt.
• Người dùng ứng dụng phải là quản trị viên doanh nghiệp của tài khoản kinh doanh sẽ được thêm số điện thoại xác minh trước của doanh nghiệp.
• Mã truy cập dành cho Người dùng hoặc Mã truy cập dành cho Người dùng hệ thống.
• Quyền business_management.
• Số điện thoại của doanh nghiệp phải hợp lệ.

Giới hạn

• Chỉ sử dụng được cho quy trình Đăng ký nhúng sẵn mới. Hãy tham khảo tài liệu Nhúng quy trình đăng ký để tìm hiểu cách kích hoạt quy trình mới.
• Bạn chịu trách nhiệm theo dõi những người đã xác nhận sở hữu số điện thoại xác minh trước của doanh nghiệp.
• Nếu khách hàng cuối không xác nhận sở hữu số điện thoại xác minh trước của doanh nghiệp trong quy trình Đăng ký nhúng sẵn trong vòng 90 ngày kể từ ngày xác minh, số điện thoại đó sẽ chuyển về trạng thái chưa được xác minh và phải được xác minh lại để khôi phục trạng thái trong 90 ngày tiếp theo.
• Bạn không thể xác minh lại số điện thoại xác minh trước chưa được xác nhận sở hữu của doanh nghiệp cho đến 45 ngày trước khi số điện thoại đó được lên lịch chuyển về trạng thái chưa được xác minh. Thời gian này được biểu thị bằng trường verification_expiry_time.
• Nếu bạn thêm một số điện thoại vào nhóm số điện thoại xác minh trước của doanh nghiệp (Bước 1) nhưng không xác minh số đó trong vòng 90 ngày (Bước 3), số điện thoại đó sẽ bị gỡ khỏi nhóm và bạn sẽ phải thêm lại.

Tạo số điện thoại xác minh trước

Làm theo các bước sau để tạo số điện thoại xác minh trước của doanh nghiệp, hiển thị số điện thoại đó trong quy trình Đăng ký nhúng sẵn và đăng ký số đó sau khi khách hàng cuối xác nhận sở hữu.

Bước 1: Tạo số điện thoại xác minh trước của doanh nghiệp

Sử dụng điểm cuối Tài khoản kinh doanh > Thêm số điện thoại để tạo số điện thoại xác minh trước của doanh nghiệp cho doanh nghiệp của bạn. Hành động này sẽ thêm số điện thoại đó vào nhóm số điện thoại của bạn.

Cú pháp yêu cầu

POST /<BUSINESS_ACCOUNT_ID>/add_phone_numbers
  ?phone_number=<PHONE_NUMBER>

Phản hồi

Sau khi thành công, API sẽ trả về ID Số điện thoại xác minh trước cho WhatsApp Business. Hãy ghi lại giá trị này để sử dụng trong yêu cầu tiếp theo.

{
  "id": "<WHATSAPP_BUSINESS_PRE_VERIFIED_PHONE_NUMBER_ID>"
}

Yêu cầu mẫu

curl -X POST 'https://graph.facebook.com/v19.0/506914307656634/add_phone_numbers?phone_number=15550783881' \
-H 'Authorization: Bearer EAAJB...'

Phản hồi mẫu

{
  "id": "106540352242922"
}

Hãy xem tài liệu tham khảo về điểm cuối Tài khoản kinh doanh > Thêm số điện thoại để biết định dạng số điện thoại và các thông số truy vấn được hỗ trợ.

Bước 2: Yêu cầu mã xác minh

Sử dụng điểm cuối Số điện thoại xác minh trước cho WhatsApp Business > Yêu cầu mã để yêu cầu mật khẩu một lần qua SMS hoặc tin nhắn thoại cho số điện thoại xác minh trước của doanh nghiệp mà bạn mới tạo.

Cú pháp yêu cầu

POST /<WHATSAPP_BUSINESS_PRE_VERIFIED_PHONE_NUMBER_ID>/request_code
  ?code_method=<CODE_METHOD>
  &language=<LANGUAGE>

Phản hồi

Sau khi thành công, API sẽ trả về true.

{
  "success": <SUCCESS>
}

Ngoài ra, chúng tôi sẽ gửi SMS hoặc tin nhắn thoại chứa mật khẩu một lần đến số điện thoại này. Hãy ghi lại mật khẩu một lần để sử dụng trong yêu cầu tiếp theo.

Cú pháp SMS chứa mật khẩu một lần

WhatsApp code <CODE>

Cú pháp tin nhắn thoại chứa mật khẩu một lần

Được lặp lại 3 lần.

Verification code is <CODE>

Yêu cầu mẫu

curl -X POST 'https://graph.facebook.com/v19.0/106540352242922/request_code?code_method=SMS&language=en_US' \
-H 'Authorization: Bearer EAAJB...'

Phản hồi mẫu

{
  "success": true
}

Tin nhắn SMS mẫu chứa mật khẩu một lần

WhatsApp code 123-456

Tin nhắn thoại mẫu chứa mật khẩu một lần

Được lặp lại 3 lần.

Verification code is 123456

Hãy xem tài liệu tham khảo về điểm cuối Số điện thoại xác minh trước cho WhatsApp Business > Yêu cầu mã để biết các phương thức lập trình, ngôn ngữ và thông số truy vấn được hỗ trợ.

Bước 3: Xác minh số điện thoại

Sử dụng điểm cuối Số điện thoại xác minh trước cho WhatsApp Business > Xác minh mã để xác minh số điện thoại của doanh nghiệp bằng mật khẩu một lần.

Cú pháp yêu cầu

POST /<WHATSAPP_BUSINESS_PRE_VERIFIED_PHONE_NUMBER_ID>/verify_code
  ?code=<CODE>

Phản hồi

Sau khi thành công, API sẽ trả về true và số điện thoại của doanh nghiệp sẽ có code_verification_status được đặt là VERIFIED trong 90 ngày.

{
  "success": <SUCCESS>
}

Yêu cầu mẫu

curl -X POST 'https://graph.facebook.com/v19.0/106540352242922/verify_code?code=123456' \
-H 'Authorization: Bearer EAAJB...'

Phản hồi mẫu

{
  "success": true
}

Hãy xem tài liệu tham khảo về điểm cuối Số điện thoại xác minh trước cho WhatsApp Business > Xác minh mã để biết các thông số truy vấn được hỗ trợ.

Sau khi bạn có số điện thoại (hoặc một nhóm số điện thoại) xác minh trước của doanh nghiệp có trạng thái đã xác minh, hãy hiển thị số đó trong quy trình Đăng ký nhúng sẵn mới.

Hiển thị số điện thoại xác minh trước trong quy trình Đăng ký nhúng sẵn

Bạn có thể hiển thị số điện thoại xác minh trước của doanh nghiệp trong quy trình Đăng ký nhúng sẵn mới thông qua dữ liệu trong mẫu điền sẵn. Để thực hiện việc này, hãy thêm một đối tượng preVerifiedPhone có thuộc tính ids vào đối tượng setup và chỉ định ID số điện thoại xác minh trước của doanh nghiệp dưới dạng mảng chuỗi cho thuộc tính ids:

{
  scope: '<SCOPE>',
  extras: {
    feature: '<FEATURE>',
    setup: {
      preVerifiedPhone: {
        ids: [<IDS>]
      }
    }
  }
}

Ví dụ:

{
  scope: 'business_management,whatsapp_business_management',
  extras: {
    feature: 'whatsapp_embedded_signup',
    version: 2,
    setup: {
	business: {
	  name: 'Acme Inc.',
	  email: 'johndoe@acme.com',
	  phone: {
	    code: 1,
	    number: '6505551234'
        },
	  website: 'https://www.acme.com',
        address: {
          streetAddress1: '1 Acme Way',
          city: 'Acme Town',
          state: 'CA',
          zipPostal: '94000',
          country: 'US'
        },
        timezone: 'UTC-08:00'
      },
      phone: {
        displayName: 'Acme Inc.',
        category: 'ENTERTAIN',
        description: 'Gears and widgets'
      },
      preVerifiedPhone: {
        ids: ['106540352242922','105954558954427']
      }
    }
  }
}

Lưu ý rằng nếu khách hàng không xác nhận sở hữu số điện thoại xác minh trước của doanh nghiệp có trạng thái VERIFIED trong vòng 90 ngày kể từ ngày xác minh, số điện thoại đó sẽ được đặt về trạng thái UNVERIFIED nhưng vẫn xuất hiện trong quy trình Đăng ký nhúng sẵn mới. Nếu cố xác nhận sở hữu một số điện thoại chưa được xác minh, khách hàng cuối sẽ phải tự hoàn tất quy trình xác minh, nghĩa là họ phải yêu cầu bạn cung cấp mật khẩu một lần.

Để tránh trải nghiệm người dùng tiêu cực này, bạn nên theo dõi thời điểm xác minh số điện thoại và xác minh lại trước khi số điện thoại đó chuyển về trạng thái chưa được xác minh.

Nếu bạn không biết chắc thời điểm xác minh lần gần nhất một số điện thoại xác minh trước cụ thể của doanh nghiệp, hãy truy vấn điểm cuối Số điện thoại xác minh trước cho WhatsApp Business và đọc các trường code_verification_time và verification_expiry_time. Các trường này cho biết thời điểm xác minh gần đây nhất và thời gian hết hạn xác minh của số điện thoại đó.

Xác định liệu số điện thoại đã được xác nhận sở hữu thông qua quy trình Đăng ký nhúng sẵn hay chưa

Hãy xem phần Lấy ID số điện thoại đã xác nhận sở hữu.

Lấy ID số điện thoại đã xác nhận sở hữu

Thực hiện yêu cầu GET trên điểm cuối Tài khoản WhatsApp Business > Số điện thoại. Hệ thống sẽ trả về tất cả Số điện thoại WhatsApp Business trên một Tài khoản WhatsApp Business.

Phân tích cú pháp cho thuộc tính display_phone_number trong mỗi đối tượng được trả về trong tập kết quả này. Nếu đối tượng có số điện thoại hiển thị (ví dụ 16505551234) chính là giá trị display_phone_number thì số điện thoại đó đã được xác nhận sở hữu. Hãy sao chép giá trị thuộc tính id của đối tượng này vì đây là ID của đối tượng Số điện thoại WhatsApp Business mới biểu thị số điện thoại này (ID cũ sẽ không còn hoạt động nữa).

Ngoài ra, bạn có thể sử dụng cùng một điểm cuối có tùy chọn mở rộng field để yêu cầu trường display_phone_number và chỉ định số điện thoại hiển thị. Ví dụ:

GET /102290129340398/phone_numbers?display_phone_number=16505551234

Nếu hệ thống trả về một đối tượng Số điện thoại WhatsApp Business kèm theo số điện thoại hiển thị đó thì số điện thoại này đã được xác nhận sở hữu và bạn nên sao chép id của đối tượng đó.

Lấy số điện thoại xác minh trước của doanh nghiệp

Sử dụng điểm cuối Tài khoản kinh doanh > Số điện thoại xác minh trước để lấy danh sách tất cả đối tượng Số điện thoại xác minh trước cho WhatsApp Business - bất kể trạng thái xác minh - trong nhóm số điện thoại xác minh trước của doanh nghiệp thuộc tài khoản kinh doanh của bạn:

GET /<BUSINESS_ACCOUNT_ID>/preverified_numbers

Hệ thống sẽ tự động sắp xếp kết quả theo thứ tự thời gian tạo. Bạn cũng có thể yêu cầu trường code_verification_status thông qua tùy chọn mở rộng trường để yêu cầu API chỉ trả về số điện thoại xác minh trước của doanh nghiệp có trạng thái xác minh đã chỉ định:

GET /<BUSINESS_ACCOUNT_ID>/preverified_numbers?code_verification_status=VERIFIED

Chia sẻ và hủy chia sẻ số điện thoại xác minh trước

Gửi yêu cầu POST đến điểm cuối Doanh nghiệp > Chia sẻ số điện thoại xác minh trước để chia sẻ số điện thoại xác minh trước của doanh nghiệp với các đối tác kinh doanh hoặc gửi yêu cầu DELETE đến chính điểm cuối này để hủy chia sẻ.

Các đối tác kinh doanh có thể hiển thị số điện thoại xác minh trước của doanh nghiệp đã được chia sẻ trong quy trình Đăng ký nhúng sẵn.

Nếu chia sẻ số điện thoại với nhiều đối tác kinh doanh, bạn nên tư vấn cho các đối tác lấy danh sách số điện thoại xác minh trước đã được chia sẻ trước khi hiển thị các số đó trong quy trình Đăng ký nhúng sẵn. Điều này giúp ngăn đối tác cố hiển thị một số điện thoại đã được xác nhận sở hữu (các số điện thoại đã xác nhận sở hữu không xuất hiện trong quy trình nhưng đối tác có thể không biết điều này và thắc mắc vì sao số điện thoại đó không xuất hiện).

Cú pháp yêu cầu chia sẻ

POST /<BUSINESS_ID>/share_preverified_numbers
  ?partner_business_id=<PARTNER_BUSINESS_ID>
  &preverified_id=<PREVERIFIED_ID>

Cú pháp yêu cầu hủy chia sẻ

DELETE /<BUSINESS_ID>/share_preverified_numbers
  ?partner_business_id=<PARTNER_BUSINESS_ID>
  &preverified_id=<PREVERIFIED_ID>

Phản hồi

Sau khi thành công, API sẽ trả về true. Nếu chia sẻ, hãy thông báo cho đối tác kinh doanh về số điện thoại xác minh trước mà bạn mới chia sẻ và cung cấp ID số điện thoại đó. Nếu bạn hủy chia sẻ, số điện thoại đó sẽ không còn xuất hiện trong bản triển khai quy trình Đăng ký nhúng sẵn của đối tác nữa.

{
  "success": <SUCCESS>
}

Yêu cầu chia sẻ mẫu

curl -X POST 'https://graph.facebook.com/v17.0/share_preverified_numbers?partner_business_id=506914307656634&preverified_id=1706193509821738' \
-H 'Authorization: Bearer EAAH0...'

Yêu cầu hủy chia sẻ mẫu

curl -X DELETE 'https://graph.facebook.com/v17.0/share_preverified_numbers?partner_business_id=506914307656634&preverified_id=1706193509821738' \
-H 'Authorization: Bearer EAAH0...'

Phản hồi mẫu

{
  "success": true
}

Đăng ký số điện thoại xác minh trước theo lập trình

Bạn có thể hoàn toàn bỏ qua việc chọn số điện thoại trong quy trình Đăng ký nhúng sẵn và đăng ký số điện thoại xác minh trước của doanh nghiệp trên Tài khoản WhatsApp Business của khách hàng cuối đã tích hợp theo lập trình. Để thực hiện, hãy làm theo các bước trong tài liệu Đăng ký số điện thoại, nhưng sử dụng ID số điện thoại xác minh trước của doanh nghiệp trong Bước 1, sau đó chuyển đến Bước 4.

Cú pháp yêu cầu

Sử dụng yêu cầu này để tạo một Số điện thoại WhatsApp Business trên Tài khoản WhatsApp Business bằng cách dùng ID số điện thoại xác minh trước của doanh nghiệp. Bước này sẽ thay thế Bước 1.

POST /<WHATSAPP_BUSINESS_ACCOUNT_ID>/phone_numbers

Nội dung yêu cầu POST

{
  "preverified_id": "<PREVERIFIED_ID>",
  "country_dial_code": "<COUNTRY_DIAL_CODE>",
  "display_phone_number": "<DISPLAY_PHONE_NUMBER>",
  "verified_name": "<VERIFIED_NAME>"
}

Thuộc tính

Cú pháp phản hồi

Sau khi thành công, API sẽ trả về ID của Số điện thoại WhatsApp Business. Sử dụng ID này để đăng ký số điện thoại (Bước 4 trong tài liệu Đăng ký số điện thoại).

{
  "id": "<ID>"
}

Thuộc tính phản hồi

Yêu cầu mẫu

curl 'https://graph.facebook.com/v19.0/506914307656634/phone_numbers' \
-H 'Content-Type: text/plain' \
-H 'Authorization: Bearer EAAH7...' \
-d '
{
  "preverified_id": "6635066806614622",
  "country_dial_code": "1",
  "display_phone_number": "5550783881",
  "verified_name": "Lucky Shrub"
}'

Phản hồi mẫu

{
  "id": "108692048990658"
}