Mẫu xác thực

Nếu ứng dụng di động của bạn cung cấp cho người dùng tùy chọn nhận mật khẩu một lần hoặc mã xác minh qua WhatsApp, bạn phải sử dụng mẫu xác thực.

Mẫu xác thực bao gồm:

• Văn bản cố định đặt sẵn: <VERIFICATION_CODE> là mã xác minh của bạn.
• Tuyên bố miễn trừ trách nhiệm về bảo mật (không bắt buộc): Vì lý do bảo mật, vui lòng không chia sẻ mã này.
• Cảnh báo hết hạn (không bắt buộc): Mã này sẽ hết hạn sau <NUM_MINUTES> phút.
• Nút tự động điền bằng một lần nhấn, nút sao chép mã hoặc không có nút nào nếu sử dụng mẫu không cần nhấn.

Nút tự động điền bằng một lần nhấn là giải pháp ưu tiên vì mang lại trải nghiệm tốt nhất cho người dùng. Tuy nhiên, nút tự động điền bằng một lần nhấn hiện chỉ được hỗ trợ trên Android và bạn cần thực hiện những thay đổi khác cho mã của ứng dụng.

Hãy xem các nguyên tắc khác để biết thời điểm thích hợp nên sử dụng mẫu xác thực.

Mẫu xác thực có nút tự động điền bằng một lần nhấn

Mẫu xác thực có nút tự động điền bằng một lần nhấn.

Khi người dùng WhatsApp nhấn vào nút tự động điền, ứng dụng WhatsApp sẽ kích hoạt một hoạt động để mở ứng dụng của bạn và cung cấp mật khẩu hoặc mã cho ứng dụng.

Hãy xem phần Mẫu xác thực có nút tự động điền bằng một lần nhấn để tìm hiểu cách sử dụng.

Mẫu xác thực có nút sao chép mã

Với mẫu xác thực có nút sao chép mã, bạn có thể gửi mật khẩu một lần hoặc mã kèm theo nút sao chép mã cho người dùng.

Khi người dùng WhatsApp nhấn vào nút sao chép mã, ứng dụng WhatsApp sẽ sao chép mật khẩu hoặc mã vào bộ nhớ tạm của thiết bị. Sau đó, người dùng có thể chuyển sang ứng dụng của bạn và dán mật khẩu hoặc mã này vào ứng dụng đó.

Hãy xem phần Mẫu xác thực có nút sao chép mã để tìm hiểu cách sử dụng.

Mẫu xác thực không cần nhấn

Mẫu xác thực không cần nhấn cho phép người dùng nhận mật khẩu một lần hoặc mã qua WhatsApp mà không phải rời khỏi ứng dụng của bạn.

Khi người dùng trong ứng dụng của bạn yêu cầu mật khẩu hoặc mã và bạn gửi mật khẩu/mã đó qua mẫu xác thực không cần nhấn, ứng dụng WhatsApp sẽ gửi mật khẩu hoặc mã kèm theo. Sau đó, ứng dụng của bạn có thể thu thập mật khẩu/mã đó bằng broadcast receiver.

Hãy xem phần Mẫu xác thực không cần nhấn để tìm hiểu cách sử dụng.

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

• Xác nhận số điện thoại WhatsApp của người dùng trước khi gửi mật khẩu một lần hoặc mã đến số đó.
• Giải thích rõ với người dùng rằng mật khẩu hoặc mã sẽ được gửi đến số điện thoại WhatsApp của họ, đặc biệt nếu bạn cung cấp nhiều phương thức để người dùng nhận mật khẩu hoặc mã. Hãy xem bài viết Yêu cầu đồng ý để biết thêm bí quyết khác.
• Khi người dùng dán mật khẩu hoặc mã vào ứng dụng của bạn hay khi ứng dụng đó nhận được mật khẩu/mã trong quy trình của nút tự động điền bằng một lần nhấn, hãy giải thích rõ với người dùng rằng ứng dụng của bạn đã chụp lại mật khẩu/mã đó.

Xem thêm phần Cách tốt nhất để xác thực người dùng qua WhatsApp.

Thời gian tồn tại

Nếu không thể gửi tin nhắn cho người dùng WhatsApp, chúng tôi sẽ tiếp tục tìm cách gửi tin nhắn trong một khoảng thời gian (được gọi là thời gian tồn tại).

Theo mặc định, tin nhắn có thời gian tồn tại là 30 ngày. Tuy nhiên, mẫu xác thực mới tạo có thời gian tồn tại mặc định là 10 phút.

Nếu không thể gửi mẫu xác thực trong khoảng thời gian vượt quá thời gian tồn tại, chúng tôi sẽ ngừng thử lại và hủy tin nhắn. Nếu thời gian yêu cầu gửi tin nhắn mẫu xác thực vượt quá thời gian tồn tại và bạn không nhận được webhook nào, nghĩa là tin nhắn đó đã bị hủy.

Để ghi đè thời gian tồn tại mặc định khi tạo mẫu xác thực, hãy thêm thuộc tính message_send_ttl_seconds với giá trị được đặt trong khoảng từ 60 đến 600 giây.

Các mẫu hiện có được tạo trước khi chức năng này ra mắt có thời gian tồn tại là 30 ngày. Nếu muốn, bạn có thể chỉnh sửa mẫu hiện có và ghi đè thời gian tồn tại của mẫu đó bằng cách đặt thuộc tính message_send_ttl_seconds.

Bạn cũng có thể đặt thuộc tính message_send_ttl_seconds của mẫu xác thực thành -1. Cài đặt này sẽ đặt thời gian tồn tại là 30 ngày.

Bạn nên đặt thời gian tồn tại cho tất cả mẫu xác thực của mình (tốt hơn là bằng hoặc nhỏ hơn thời hạn của mã) để đảm bảo khách hàng chỉ nhận được tin nhắn khi mã vẫn còn sử dụng được.

Lưu ý rằng hệ thống có thể chậm trễ đôi chút khi gửi webhook tin nhắn không thành công. Vì vậy, bạn nên đệm thêm chút thời gian khi phỏng đoán tin nhắn bị hủy.

Gửi tin nhắn mẫu xác thực

Sử dụng API Đám mây hoặc API Tại chỗ để gửi mẫu xác thực đã phê duyệt trong tin nhắn mẫu.

• Gửi tin nhắn mẫu xác thực bằng API Đám mây
• Gửi tin nhắn mẫu xác thực bằng API Tại chỗ

Bản xem trước mẫu

Bạn có thể tạo bản xem trước văn bản mẫu xác thực bằng nhiều ngôn ngữ khác nhau, có hoặc không có chuỗi đề xuất bảo mật và chuỗi thời hạn mã thông qua điểm cuối Tài khoản WhatsApp Business > Bản xem trước mẫu tin nhắn.

Cú pháp yêu cầu

GET /<WHATSAPP_BUSINESS_ACCOUNT_ID>/message_template_previews
  ?category=AUTHENTICATION,
  &language=<LANGUAGE>, // Optional
  &add_security_recommendation=<ADD_SECURITY_RECOMMENDATION>, // Optional
  &code_expiration_minutes=<CODE_EXPIRATION_MINUTES>, // Optional
  &button_types=<BUTTON_TYPES> // Optional

Thông số chuỗi truy vấn

Yêu cầu mẫu

curl 'https://graph.facebook.com/v17.0/102290129340398/message_template_previews?category=AUTHENTICATION&languages=en_US,es_ES&add_security_recommendation=true&code_expiration_minutes=10&button_types=OTP' \
-H 'Authorization: Bearer EAAJB...'

Phản hồi mẫu

{
  "data": [
    {
      "body": "*{{1}}* is your verification code. For your security, do not share this code.",
      "buttons": [
        {
          "autofill_text": "Autofill",
          "text": "Copy code"
        }
      ],
      "footer": "This code expires in 10 minutes.",
      "language": "en_US"
    },
    {
      "body": "Tu código de verificación es *{{1}}*. Por tu seguridad, no lo compartas.",
      "buttons": [
        {
          "autofill_text": "Autocompletar",
          "text": "Copiar código"
        }
      ],
      "footer": "Este código caduca en 10 minutos.",
      "language": "es_ES"
    }
  ]
}

Quản lý hàng loạt

Sử dụng điểm cuối Tài khoản WhatsApp Business > Cập nhật/chèn mẫu tin nhắn để cập nhật hoặc tạo hàng loạt mẫu xác thực bằng nhiều ngôn ngữ, có hoặc không có cảnh báo hết hạn và bảo mật không bắt buộc.

Nếu bạn đã có sẵn mẫu với tên và ngôn ngữ phù hợp, mẫu đó sẽ được cập nhật nội dung yêu cầu. Nếu không, hệ thống sẽ tạo mẫu mới.

Cú pháp yêu cầu

POST /<WHATSAPP_BUSINESS_ACCOUNT_ID>/upsert_message_templates

Nội dung yêu cầu POST

{
  "name": "<NAME>",
  "languages": [<LANGUAGES>],
  "category": "AUTHENTICATION",
  "components": [
    {
      "type": "BODY",
      "add_security_recommendation": <ADD_SECURITY_RECOMMENDATION> // Optional
    },
    {
      "type": "FOOTER",
      "code_expiration_minutes": <CODE_EXPIRATION_MINUTES> // Optional
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "OTP",
          "otp_type": "<OTP_TYPE>",
          "package_name": "<PACKAGE_NAME>", // One-tap buttons only
          "signature_hash": "SIGNATURE_HASH>", // One-tap buttons only
        }
      ]
    }
  ]
}

Thuộc tính

Hệ thống hỗ trợ tất cả thuộc tính tạo mẫu, ngoại trừ các thuộc tính sau:

• Thuộc tính language không được hỗ trợ. Thay vào đó, hãy sử dụng languages và đặt giá trị thuộc tính là mảng chuỗi mã ngôn ngữ và địa phương. Ví dụ: ["en_US","es_ES","fr"].
• Thuộc tính text không được hỗ trợ.
• Thuộc tính autofill_text không được hỗ trợ.

Ví dụ về yêu cầu sao chép mã

Ví dụ này tạo 3 mẫu xác thực bằng tiếng Anh, tiếng Tây Ban Nha và tiếng Pháp có nút sao chép mã. Mỗi mẫu đều có tên là "authentication_code_copy_code_button" và có chứa đề xuất bảo mật cũng như thời hạn.

curl 'https://graph.facebook.com/v17.0/102290129340398/upsert_message_templates' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "name": "authentication_code_copy_code_button",
  "languages": ["en_US","es_ES","fr"],
  "category": "AUTHENTICATION",
  "components": [
    {
      "type": "BODY",
      "add_security_recommendation": true
    },
    {
      "type": "FOOTER",
      "code_expiration_minutes": 10
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "OTP",
          "otp_type": "COPY_CODE"
        }
      ]
    }
  ]
}'

Ví dụ về yêu cầu tự động điền bằng một lần nhấn

Ví dụ này (1) cập nhật mẫu hiện tại có tên "authentication_code_autofill_button" và ngôn ngữ "en_US", đồng thời (2) tạo 2 mẫu xác thực mới bằng tiếng Tây Ban Nha và tiếng Pháp có nút tự động điền bằng một lần nhấn. Cả hai mẫu mới tạo đều có tên là "authentication_code_autofill_button" và có chứa đề xuất bảo mật cũng như thời hạn.

curl 'https://graph.facebook.com/v17.0/102290129340398/upsert_message_templates' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "name": "authentication_code_autofill_button",
  "languages": ["en_US","es_ES","fr"],
  "category": "AUTHENTICATION",
  "components": [
    {
      "type": "BODY",
      "add_security_recommendation": true
    },
    {
      "type": "FOOTER",
      "code_expiration_minutes": 15
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "OTP",
          "otp_type": "ONE_TAP",
          "package_name": "com.example.luckyshrub",
          "signature_hash": "K8a%2FAINcGX7"
        }
      ]
    }
  ]
}'

Phản hồi mẫu

{
  "data": [
    {
      "id": "954638012257287",
      "status": "APPROVED",
      "language": "en_US"
    },
    {
      "id": "969725527415202",
      "status": "APPROVED",
      "language": "es_ES"
    },
    {
      "id": "969725530748535",
      "status": "APPROVED",
      "language": "fr"
    }
  ]
}

Ứng dụng mẫu

Hãy xem Ứng dụng mẫu gửi/nhận mật khẩu một lần (OTP) trên WhatsApp dành cho Android trên Github. Ứng dụng mẫu này minh họa cách gửi/nhận mã và mật khẩu OTP qua API, cách tích hợp các nút sao chép mã và tự động điền bằng một lần nhấn, cách tạo mẫu, cũng như cách khởi động máy chủ mẫu.

Xem thêm

• Tài khoản kinh doanh chính thức - Bạn nên yêu cầu trạng thái Tài khoản kinh doanh chính thức để tạo lòng tin với người dùng, nhờ đó giảm khả năng người dùng bỏ qua hoặc phớt lờ tin nhắn của bạn.
• Webhooks cho thông báo đã đọc - Bạn nên đăng ký trường webhooks tin nhắn để có thể nhận được thông báo khi người dùng nhận và đọc mẫu xác thực có nút OTP của bạn. Hãy xem bài viết Webhooks cho API Đám mây hoặc Webhooks cho API Tại chỗ.