WhatsApp Business 平台

經過預先驗證的電話號碼

本文件會講解如何在新的內嵌註冊流程中為您的最終客戶提供經過預先驗證的商家電話號碼。經過預先驗證的商家電話號碼是指您已驗證的商家電話號碼，這樣最終客戶便無需再聯絡您來獲取單次密碼。

Screenshot of pre-verifed phone numbers in Embedded Signup flow

請注意，經過預先驗證的商家電話號碼是由 WhatsApp Business 經過預先驗證的電話號碼物件表示，為臨時物件。當最終客戶選擇其中一組號碼並完成新的內嵌註冊流程時，此臨時物件便會換為 WhatsApp Business 電話號碼物件，而您必須獲取該新物件的編號，才能註冊有關號碼。

要求

限制

  • 只適用於新的內嵌註冊流程。請參閱內嵌註冊流程文件，了解如何啟用此新流程。
  • 您需要負責追蹤認領了經過預先驗證商家電話號碼的客戶。
  • 如果在驗證後 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": "<WHATSAPP_BUSINESS_PRE_VERIFIED_PHONE_NUMBER_ID>"
}

要求範例

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

回應範例

{
  "id": "106540352242922"
}

請參閱商業帳戶 > 新增電話號碼端點參考資料，了解支援的電話號碼格式和查詢參數。

第 2 步：要求驗證碼

使用 WhatsApp Business 經過預先驗證的電話號碼 > 要求代碼端點，要求透過短訊或語音訊息為新加入的經過預先驗證商家電話號碼取得單次密碼。

要求語法

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

回應

成功的話，API 將傳回 true。

{
  "success": <SUCCESS>
}

此外，我們還會向此電話號碼傳送包含單次密碼的短訊或語音訊息。請記下此單次密碼，以便在後續要求中使用。

單次密碼短訊語法

WhatsApp code <CODE>

單次密碼語音訊息語法

重複此步驟 3 次。

Verification code is <CODE>

要求範例

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

回應範例

{
  "success": true
}

單次密碼短訊範例

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 將設為 VERIFIED 90 天。

{
  "success": <SUCCESS>
}

要求範例

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

回應範例

{
  "success": true
}

請參閱 WhatsApp Business 經過預先驗證的電話號碼 > 驗證代碼端點參考資料，了解支援的查詢參數。

取得一個或一組處於已驗證狀態的經過預先驗證商家電話號碼後，您可在新的內嵌註冊流程中顯示此等號碼。

在內嵌註冊流程中顯示經過預先驗證的號碼

您可以透過預先填妥的表格資料，在新的內嵌註冊流程中顯示經過預先驗證的商家電話號碼。為此，請在 setup 物件中加入 preVerifiedPhone 物件和 ids 屬性，並將經過預先驗證的商家電話號碼編號以字串陣列的形式分配到 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']
      }
    }
  }
}

請注意，如果在驗證後 90 天內，具有 VERIFIED 狀態的經過預先驗證商家電話號碼仍未有人認領，此號碼便會恢復為 UNVERIFIED 狀態，但仍會出現在新的內嵌註冊流程當中。如果最終客戶試圖認領未經驗證的號碼，便必須自行完成驗證，亦即必須向您索取單次密碼。

為避免出現這種欠佳體驗，建議您記錄號碼的驗證時間，並在號碼恢復為未經驗證狀態之前重新驗證。

如果您不確定指定的經過預先驗證商家電話號碼上次是在什麼時間驗證，可查詢 WhatsApp Business 經過預先驗證的電話號碼端點，並讀取 code_verification_time 和 verification_expiry_time 欄位；這兩個欄位分別標示最近驗證時間和驗證過期時間。

確定號碼是否已在內嵌註冊流程中獲認領

請參閱獲取已認領的電話號碼編號部分。

獲取已認領的電話號碼編號

在 WhatsApp Business 帳戶 > 電話號碼端點上執行 GET 要求，此端點將傳回特定 WhatsApp Business 帳戶上的所有 WhatsApp Business 電話號碼。

為結果組合中傳回的每個物件剖析 display_phone_number 屬性。如果物件的 display_phone_number 值是顯示電話號碼（例如 16505551234），則表示其已獲認領。請複製物件的 id 屬性值，因為這是現在代表此號碼的新 WhatsApp Business 電話號碼物件編號；舊的編號將會失效。

除此之外，您也可以使用同一端點並加入 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。如要共用，請將新共用的經過預先驗證號碼告知商家合作夥伴，並向其提供該號碼的編號。如取消共用，該號碼將不再出現在合作夥伴執行的內嵌註冊流程中。

{
  "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 步中使用經過預先驗證的商家電話號碼編號，然後略過至第 4 步。

要求語法

使用此要求在 WhatsApp Business 帳戶上，以經過預先驗證商家電話號碼的編號建立 WhatsApp Business 電話號碼。這將替代第 1 步。

POST /<WHATSAPP_BUSINESS_ACCOUNT_ID>/phone_numbers

帖子內文

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

屬性

預留位置說明範例值

<PREVERIFIED_ID>

字串

此為必要項目。


經過預先驗證商家電話號碼的編號。

6635066806614622

<COUNTRY_DIAL_CODE>

字串

此為必要項目。


經過預先驗證商家電話號碼的國家／地區撥號代碼。

1

<DISPLAY_PHONE_NUMBER>

字串

此為必要項目。


經過預先驗證商家電話號碼的顯示電話號碼。

5550783881

<VERIFIED_NAME>

字串

此為必要項目。


經過預先驗證商家電話號碼的顯示名稱。

Lucky Shrub

回覆語法

成功的話，API 回應中將包含 WhatsApp Business 電話號碼的編號。使用此編號註冊電話號碼，即註冊電話號碼文件中的第 4 步。

{
  "id": "<ID>"
}

回應屬性

預留位置說明範例值

<ID>

WhatsApp Business 電話號碼的編號。


此物件將取代 WhatsApp Business 經過預先驗證的電話號碼物件。

108692048990658

要求範例

curl 'https://graph.facebook.com/v20.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"
}