인증 템플릿

모바일 앱에서 WhatsApp을 통해 일회용 비밀번호나 인증 코드를 받는 옵션을 사용자에게 제공하는 경우 인증 템플릿을 사용해야 합니다.

인증 템플릿은 다음과 같이 구성됩니다.

• 고정된 기본 설정 텍스트: <VERIFICATION_CODE>가 인증 코드입니다.
• 선택적 보안 고지 사항: 보안을 위해 이 코드를 공유하지 마세요.
• 선택적 만료 경고: 이 코드는 <NUM_MINUTES>분 후에 만료됩니다.
• 한 번 눌러서 자동 입력 버튼 또는 코드 복사 버튼. 제로 탭을 사용하는 경우에는 버튼이 없습니다.

한 번 눌러서 자동 입력 버튼은 최적의 사용자 경험을 제공하므로 선호되는 솔루션입니다. 그러나 해당 버튼은 현재 Android에서만 지원되며 앱 코드를 추가로 변경해야 합니다.

인증 템플릿을 사용해야 하는 경우를 보려면 추가 가이드라인을 참조하세요.

한 번 눌러서 자동 입력 인증 템플릿

인증 템플릿에는 한 번 눌러서 자동 입력 버튼이 포함됩니다.

WhatsApp 사용자가 자동 입력 버튼을 누르면 WhatsApp 클라이언트가 앱을 열어서 비밀번호 또는 코드를 전달하는 활동을 트리거합니다.

사용 방법에 대해 알아보려면 한 번 눌러서 자동 입력 인증 템플릿을 참조하세요.

코드 복사 인증 템플릿

코드 복사 인증 템플릿을 사용하면 코드 복사 버튼과 함께 일회용 비밀번호 또는 코드를 사용자에게 보낼 수 있습니다.

WhatsApp 사용자가 코드 복사 버튼을 누르면 WhatsApp 클라이언트가 비밀번호 또는 코드를 기기 클립보드에 복사합니다. 그러면 사용자가 앱으로 전환하여 비밀번호나 코드를 앱에 붙여넣을 수 있습니다.

사용 방법에 대해 알아보려면 코드 복사 인증 템플릿을 참조하세요.

제로 탭 인증 템플릿

제로 탭 인증 템플릿을 사용하면 사용자가 앱을 떠나지 않고 WhatsApp을 통해 일회용 비밀번호 또는 코드를 받을 수 있습니다.

앱 사용자가 비밀번호나 코드를 요청하고 비즈니스가 제로 탭 인증 템플릿을 통해 비밀번호나 코드를 전달할 경우, WhatsApp 클라이언트는 포함된 비밀번호나 코드를 브로드캐스트합니다. 그러면 앱이 브로드캐스트 수신기로 이를 캡처할 수 있습니다.

사용 방법을 알아보려면 제로 탭 인증 템플릿을 참조하세요.

모범 사례

• 사용자의 WhatsApp 전화번호를 확인한 다음, 일회용 비밀번호나 코드를 해당 전화번호로 보내세요.
• 사용자에게 비밀번호나 코드가 WhatsApp 전화번호에 전달된다는 점을 명확히 알리세요. 특히 사용자가 비밀번호나 코드 전달을 받는 방법이 여러 가지인 경우 이 점이 중요합니다. 추가적인 팁은 옵트인 받기를 참조하세요.
• 사용자가 비밀번호나 코드를 앱에 붙여넣거나 앱이 한 번 눌러서 자동 입력 버튼 플로를 통해 이를 수신할 경우 사용자에게 앱이 비밀번호나 코드를 캡처했음을 명확히 알리세요.

WhatsApp을 통한 사용자 인증 모범 사례도 참조하세요.

TTL(Time-To-Live)

WhatsApp 사용자에게 메시지를 전달할 수 없을 경우 TTL(Time-To-Live)이라고 하는 일정 시간 동안 WhatsApp에서 메시지를 전달하려고 계속 시도합니다.

기본적으로 메시지의 TTL은 30일이지만 새로 생성된 인증 템플릿은 기본 TTL이 10분입니다.

TTL을 초과해서도 인증 템플릿을 전달할 수 없을 경우 WhatsApp에서 재시도를 멈추고 메시지를 드롭합니다. 인증 템플릿 전송 요청 사이의 시간 간격이 TTL을 초과하고 Webhooks를 수신하지 못하는 경우 메시지가 드롭된 것으로 간주하면 됩니다.

인증 템플릿을 만들 때 기본 TTL을 재정의하려면 값을 60~600초 사이로 설정한 message_send_ttl_seconds 속성을 포함하세요.

이 기능을 제공하기 전에 만든 템플릿은 TTL이 30일입니다. 원하는 경우 기존 템플릿을 수정하고 message_send_ttl_seconds 속성을 설정하여 TTL을 재정의할 수 있습니다.

인증 템플릿의 message_send_ttl_seconds 속성을 -1로 설정할 수도 있습니다. 그러면 TTL이 30일로 설정됩니다.

모든 인증 템플릿에 코드 만료 시간 이내로 TTL을 설정하여 고객이 코드가 아직 사용 가능할 때만 메시지를 받도록 하는 것이 좋습니다.

실패한 메시지 Webhooks를 전달할 때 다소 지연이 발생할 수 있으므로 드롭을 나타낼 때 작은 버퍼를 빌드하는 것이 좋습니다.

인증 템플릿 메시지 보내기

클라우드 API 또는 온프레미스 API를 사용하여 승인된 인증 템플릿을 템플릿 메시지로 보내세요.

• 클라우드 API를 통해 인증 템플릿 메시지 보내기
• 온프레미스 API를 통해 인증 템플릿 메시지 보내기

템플릿 미리 보기

WhatsApp Business 계정 > 메시지 템플릿 미리 보기 엔드포인트를 사용하여 보안 권고 사항 문자열과 코드 만료 문자열을 포함하거나 제외하고, 여러 가지 언어로 된 인증 템플릿 텍스트의 미리보기를 생성할 수 있습니다.

요청 구문

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

쿼리 문자열 매개변수

요청 예시

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...'

응답 예시

{
  "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"
    }
  ]
}

일괄 관리

WhatsApp Business 계정 > 메시지 템플릿 업데이트 삽입 엔드포인트를 사용하여 선택적 보안 및 만료 경고를 포함하거나 제외하고, 여러 언어로 인증 템플릿을 일괄 업데이트하거나 생성합니다.

일치하는 이름과 언어로 된 템플릿이 이미 존재하는 경우, 해당 템플릿은 요청 내용으로 업데이트됩니다. 그 외의 경우에는 새로운 템플릿이 생성됩니다.

요청 구문

POST /<WHATSAPP_BUSINESS_ACCOUNT_ID>/upsert_message_templates

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
        }
      ]
    }
  ]
}

속성

모든 템플릿 생성 속성이 지원되며, 예외 사항은 다음과 같습니다.

• language 속성은 지원되지 않습니다. 대신 languages를 사용하여 그 값을 언어 및 로캘 코드 문자열의 배열로 설정하세요. 예: ["en_US","es_ES","fr"].
• text 속성은 지원되지 않습니다.
• autofill_text 속성은 지원되지 않습니다.

코드 복사 요청 예시

이 예시는 영어, 스페인어, 프랑스어로 코드 복사 버튼을 포함하여 3개의 인증 템플릿을 생성합니다. 각 템플릿의 이름은 'authentication_code_copy_code_button'으로 지정되고 보안 권장 사항 및 만료 시간을 포함합니다.

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"
        }
      ]
    }
  ]
}'

한 번 눌러서 자동 입력 요청 예시

이 예시에서는 (1) 기존 템플릿을 'authentication_code_autofill_button'이라는 이름과 'en_US' 언어로 업데이트하고 (2) 한 번 눌러서 자동 입력 버튼을 포함하고 스페인어 및 프랑스어로 된 새로운 인증 템플릿 2개를 생성합니다. 새로 생성된 두 템플릿은 이름이 'authentication_code_autofill_button'으로 지정되고 보안 권장 사항 및 만료 시간을 포함합니다.

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"
        }
      ]
    }
  ]
}'

응답 예시

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

샘플 앱

GitHub에서 Android용 WhatsApp 일회용 비밀번호(OTP) 샘플 앱을 참조하세요. 이 샘플 앱은 API를 통해 OTP 비밀번호와 코드를 주고받는 방법, 한 번 눌러서 자동 입력 및 코드 복사 버튼을 통합하는 방법, 템플릿을 생성하는 방법, 샘플 서버를 시작하는 방법을 보여줍니다.

기타 참고 자료

• 공식 비즈니스 계정 — 사용자와의 신뢰를 쌓기 위해 공식 비즈니스 계정 지위를 요청할 수 있으며, 이는 사용자가 메시지를 닫거나 무시할 가능성을 줄여줍니다.
• 메시지 확인 여부를 위한 Webhooks — 사용자가 OTP 버튼이 포함된 인증 템플릿을 수신하고 읽은 경우에 알림을 받을 수 있도록 메시지 Webhooks 필드를 구독하는 것이 좋습니다. 클라우드 API용 Webhooks 또는 온프레미스 API 용 Webhooks를 참조하세요.