사전 인증된 전화번호

이 문서에서는 새로운 임베디드 가입 플로에서 최종 클라이언트에게 사전 인증된 비즈니스 전화번호를 제공하는 방법을 설명합니다. 사전 인증된 비즈니스 전화번호는 비즈니스 솔루션 제공업체에서 이미 인증한 비즈니스 전화번호이므로 최종 클라이언트가 일회용 비밀번호를 받기 위해 비즈니스 솔루션 제공업체에 연락할 필요가 없습니다.

사전 인증된 비즈니스 전화번호는 임시로 WhatsApp Business 사전 인증 전화번호 개체로 표시됩니다. 최종 클라이언트가 이러한 전화번호 중 하나를 선택하고 새로운 임베디드 가입 플로를 완료하면 임시 개체가 WhatsApp Business 전화번호 개체로 바뀌고 새로운 개체의 ID를 얻어서 해당 전화번호를 등록해야 합니다.

요구 사항

비즈니스는 승인된 솔루션 파트너여야 합니다.
앱 사용자는 사전 인증된 비즈니스 전화번호가 추가되는 비즈니스 계정의 비즈니스 운영자여야 합니다.
사용자 또는 시스템 사용자 액세스 토큰이 필요합니다.
business_management 권한이 필요합니다.
비즈니스 전화번호가 유효해야 합니다.

제한 사항

새로운 임베디드 가입 플로를 통해서만 제공됩니다. 새로운 플로를 활성화하는 방법에 대해 알아보려면 임베디드 가입 플로 문서를 참조하세요.
솔루션 파트너는 사전 인증된 비즈니스 전화번호를 요청한 사람을 추적할 책임이 있습니다.
최종 클라이언트가 인증된 지 90일 이내에 임베디드 가입 플로에서 사전 인증된 비즈니스 전화번호를 요청하지 않는 경우, 해당 전화번호는 인증되지 않은 상태로 되돌아가고 재인증을 받아야 추가로 90일 동안 인증 상태가 복원됩니다.
요청하지 않은 사전 인증된 비즈니스 전화번호는 인증되지 않은 상태로 돌아가기로 예정된 시점으로부터 45일 전까지는 재인증을 받을 수 없습니다. 이 시간은 verification_expiry_time 필드로 표시됩니다.
사전 인증된 비즈니스 전화번호 풀에 전화번호를 추가하였지만(1단계) 90일 이내에 인증하지 않는 경우(3단계), 해당 전화번호는 풀에서 삭제되므로 다시 추가해야 합니다.

사전 인증된 전화번호 만들기

이 단계에 따라 사전 인증된 비즈니스 전화번호를 만들어서 임베디드 가입에 표시하고, 최종 클라이언트가 해당 전화번호를 요청한 후에 등록합니다.

1단계: 사전 인증된 비즈니스 전화번호 만들기

비즈니스 계정 > 전화번호 추가 엔드포인트를 사용하여 비즈니스에서 사전 인증된 비즈니스 전화번호를 만듭니다. 그러면 전화번호 풀에 추가됩니다.

요청 구문

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

응답

요청이 성공하면 API가 WhatsApp Business 사전 인증 전화번호 ID를 반환합니다. 다음 요청에서 사용할 수 있도록 이 값을 캡처하세요.

{
  "id": "<WHATSAPP_BUSINESS_PRE_VERIFIED_PHONE_NUMBER_ID>"
}

요청 샘플

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

응답 샘플

{
  "id": "106540352242922"
}

지원되는 전화번호 형식과 쿼리 매개변수는 비즈니스 계정 > 전화번호 추가 엔드포인트 참고 자료를 참조하세요.

2단계: 인증 코드 요청

WhatsApp Business 사전 인증 전화번호 > 코드 요청 엔드포인트를 사용하여 새로 만든 사전 인증된 비즈니스 전화번호에 대한 일회용 비밀번호를 SMS 또는 음성을 통해 요청합니다.

요청 구문

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

응답

요청이 성공하면 API가 true를 반환합니다.

{
  "success": <SUCCESS>
}

또한 해당 전화번호에 대한 일회용 비밀번호가 포함된 SMS 또는 음성 메시지가 전송됩니다. 다음 요청에서 사용할 수 있도록 일회용 비밀번호를 캡처하세요.

일회용 비밀번호 SMS 구문

WhatsApp code <CODE>

일회용 비밀번호 음성 메시지 구문

3회 반복됩니다.

Verification code is <CODE>

요청 샘플

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

응답 샘플

{
  "success": true
}

일회용 비밀번호 SMS 메시지 샘플

WhatsApp code 123-456

일회용 비밀번호 음성 메시지 샘플

3회 반복됩니다.

Verification code is 123456

지원되는 코드 방법, 언어 및 쿼리 매개변수는 WhatsApp Business 사전 인증 전화번호 > 코드 요청 엔드포인트 참고 자료를 참조하세요.

3단계: 전화번호 인증

WhatsApp Business 사전 인증 전화번호 > 코드 인증 엔드포인트를 사용하여 일회용 비밀번호로 비즈니스 전화번호를 인증합니다.

요청 구문

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

응답

요청이 성공하면 API가 true를 반환하고 비즈니스 전화번호에서 code_verification_status가 90일 동안 VERIFIED로 설정됩니다.

{
  "success": <SUCCESS>
}

요청 샘플

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

응답 샘플

{
  "success": true
}

지원되는 쿼리 매개변수는 WhatsApp Business 사전 인증 전화번호 > 코드 인증 엔드포인트 참고 자료를 참조하세요.

사전 인증된 비즈니스 전화번호가 인증 상태가 되면 새로운 임베디드 가입 플로에 표시합니다.

임베디드 가입에 사전 인증된 전화번호 표시

미리 입력된 양식 데이터를 통해 새로운 임베디드 가입에 사전 인증된 비즈니스 전화번호를 표시할 수 있습니다. 이를 위해서는 ids 속성을 setup 개체로 설정한 preVerifiedPhone 개체를 추가하고 사전 인증된 비즈니스 전화번호의 ID를 ids 속성에 문자열 배열로 할당합니다.

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

예를 들면 다음과 같습니다.

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

VERIFIED 상태의 사전 인증된 비즈니스 전화번호를 인증 후 90일 이내에 요청하지 않을 경우, 상태는 UNVERIFIED로 설정되지만 새로운 임베디드 가입 플로에는 여전히 표시됩니다. 최종 클라이언트가 인증되지 않은 전화번호를 요청하려고 시도하는 경우, 직접 인증을 완료해야 합니다. 즉, 비즈니스 솔루션 제공업체에 일회용 비밀번호를 요청해야 합니다.

이처럼 불편한 사용자 경험을 방지하려면 전화번호를 인증한 시점을 추적하고 인증되지 않은 상태로 돌아가기 전에 다시 인증하는 것이 좋습니다.

주어진 사전 인증된 비즈니스 전화번호를 마지막으로 인증한 시점을 모를 경우, WhatsApp Business 사전 인증 전화번호 엔드포인트를 쿼리하고 최신 인증 시간과 인증 만료 시간을 나타내는 code_verification_time 및 verification_expiry_time 필드를 읽으세요.

전화번호가 임베디드 가입을 통해 요청되었는지 확인

요청된 전화번호 ID 가져오기를 참조하세요.

요청된 전화번호 ID 가져오기

WhatsApp Business 계정 > 전화번호 엔드포인트에 GET 요청을 실행하면 WhatsApp Business 계정의 모든 WhatsApp Business 전화번호가 반환됩니다.

결과 세트에 반환된 각 개체에서 display_phone_number 속성에 대해 파싱합니다. 개체에서 표시 전화번호(예: 16505551234)가 display_phone_number 값일 경우에는 해당 전화번호가 요청된 것입니다. 이제는 이 값이 이 전화번호를 나타내는 새로운 WhatsApp Business 전화번호 개체의 ID이므로 개체의 id 속성 값을 복사합니다(이전의 ID는 더 이상 작동하지 않습니다).

또는 field가 확장된 동일한 엔드포인트를 사용하여 display_phone_number 필드를 요청하고 표시 전화번호를 지정할 수 있습니다. 예를 들면 다음과 같습니다.

GET /102290129340398/phone_numbers?display_phone_number=16505551234

WhatsApp Business 전화번호 개체를 해당 표시 전화번호와 함께 반환하는 경우 해당 전화번호는 요청된 것이므로 개체의 id를 복사해야 합니다.

사전 인증된 비즈니스 전화번호 가져오기

비즈니스 계정 > 사전 인증된 전화번호 엔드포인트를 사용하여 비즈니스 계정의 사전 인증된 비즈니스 전화번호 풀에서 인증 상태와 관계없이 모든 WhatsApp Business 사전 인증 전화번호 개체의 리스트를 가져옵니다.

GET /<BUSINESS_ACCOUNT_ID>/preverified_numbers

결과는 생성 시간 순서대로 자동 정렬됩니다. 또한 필드 확장을 사용하여 code_verification_status 필드를 요청하고 API가 인증 상태가 표시된 사전 인증된 비즈니스 전화번호만 반환하도록 할 수 있습니다.

GET /<BUSINESS_ACCOUNT_ID>/preverified_numbers?code_verification_status=VERIFIED

사전 인증된 전화번호 공유 및 공유 취소

비즈니스 > 사전 인증된 전화번호 공유 엔드포인트로 POST 요청을 보내서 비즈니스 파트너에게 사전 인증된 비즈니스 전화번호를 공유하거나 동일한 엔드포인트로 DELETE 요청을 보내서 공유를 취소할 수 있습니다.

공유된 사전 인증된 비즈니스 전화번호는 비즈니스 파트너가 임베디드 가입 플로에 표시할 수 있습니다.

여러 비즈니스 파트너에게 전화번호를 공유하는 경우, 임베디드 가입에 전화번호가 표시되기 전에 파트너가 공유된 사전 인증된 전화번호 리스트를 가져오도록 권하는 것이 좋습니다. 그러면 파트너가 이미 요청된 전화번호를 표시하려고 시도할 가능성이 줄어듭니다(요청된 전화번호는 플로에 표시되지 않지만 파트너는 이를 모르고 전화번호가 표시되지 않는 이유를 궁금해할 수 있습니다).

공유 요청 구문

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

공유 취소 요청 구문

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

응답

요청이 성공하면 API가 true를 반환합니다. 공유하는 경우, 비즈니스 파트너에게 새로 공유된 사전 인증된 전화번호에 대해 알리고 해당 전화번호의 ID를 제공하세요. 공유를 취소하는 경우 해당 전화번호는 더 이상 임베디드 가입의 파트너 구현에 표시되지 않습니다.

{
  "success": <SUCCESS>
}

공유 요청 예시

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

공유 취소 요청 예시

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

응답 예시

{
  "success": true
}

사전 인증된 전화번호를 프로그래밍 방식으로 등록

임베디드 가입 전화번호 선택을 완전히 우회해서 온보딩된 최종 클라이언트의 WhatsApp Business 계정에 사전 인증된 비즈니스 전화번호를 프로그래밍 방식으로 등록할 수 있습니다. 이를 위해서는 전화번호 등록 문서의 단계를 따르되, 1단계에서 사전 인증된 비즈니스 전화번호 ID를 사용한 후 4단계로 건너뛰세요.

요청 구문

사전 인증된 비즈니스 전화번호 ID를 사용하여 WhatsApp Business 계정에서 WhatsApp Business 전화번호를 만들려면 이 요청을 사용합니다. 이는 1단계를 대체합니다.

POST /<WHATSAPP_BUSINESS_ACCOUNT_ID>/phone_numbers

POST 본문

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

속성

자리 표시자 설명 예시 값

자리 표시자	설명	예시 값
`<PREVERIFIED_ID>` 문자열	필수 항목. 사전 인증된 비즈니스 전화번호의 ID입니다.	`6635066806614622`
`<COUNTRY_DIAL_CODE>` 문자열	필수 항목. 사전 인증된 비즈니스 전화번호의 국가 다이얼 번호입니다.	`1`
`<DISPLAY_PHONE_NUMBER>` 문자열	필수 항목. 사전 인증된 비즈니스 전화번호의 표시 전화번호입니다.	`5550783881`
`<VERIFIED_NAME>` 문자열	필수 항목. 사전 인증된 비즈니스 전화번호의 표시 이름입니다.	`Lucky Shrub`

<PREVERIFIED_ID>

문자열

필수 항목.

사전 인증된 비즈니스 전화번호의 ID입니다.

6635066806614622

<COUNTRY_DIAL_CODE>

문자열

필수 항목.

사전 인증된 비즈니스 전화번호의 국가 다이얼 번호입니다.

1

<DISPLAY_PHONE_NUMBER>

문자열

필수 항목.

사전 인증된 비즈니스 전화번호의 표시 전화번호입니다.

5550783881

<VERIFIED_NAME>

문자열

필수 항목.

사전 인증된 비즈니스 전화번호의 표시 이름입니다.

Lucky Shrub

응답 구문

요청이 성공하면 API가 WhatsApp Business 전화번호의 ID로 응답합니다. 이 ID를 사용하여 해당 전화번호를 등록합니다(전화번호 등록 문서의 4단계).

{
  "id": "<ID>"
}

응답 속성

자리 표시자 설명 예시 값

자리 표시자	설명	예시 값
`<ID>`	WhatsApp Business 전화번호의 ID입니다. 이 개체는 WhatsApp Business 사전 인증 전화번호 개체를 대체했습니다.	`108692048990658`

<ID>

WhatsApp Business 전화번호의 ID입니다.

이 개체는 WhatsApp Business 사전 인증 전화번호 개체를 대체했습니다.

108692048990658

요청 예시

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

응답 예시

{
  "id": "108692048990658"
}