聯絡人

/v1/contacts

使用 contacts 節點，以在傳送訊息之前驗證用戶，藉此管理您資料庫中的 WhatsApp 用戶，並使用身分雜湊資料來驗證用戶的身分。

您可以使用 contacts 節點來執行以下動作：

• 驗證資料庫中的手機號碼是否屬於有效的 WhatsApp 帳戶。在向用戶傳送訊息前，您必須確保其 status 為 valid。
• 獲取手機號碼的 WhatsApp 編號。傳送訊息和用戶通知時，您都需要使用 WhatsApp 編號。

準備工作

您必須向顧客提供選項，讓他們選擇加入與您企業的 WhatsApp 對話。此選擇加入流程由您的企業管理。顧客選擇加入後，請使用 contacts 節點來驗證已註冊的手機號碼。如欲了解更多資訊，請參閱了解如何選擇加入 WhatsApp。

限制

• 使用此端點來驗證企業資料庫中的手機號碼是否屬於有效的 WhatsApp 帳戶
• 呼叫次數不得超過手機號碼傳送的訊息數量

政策執行

如果商家濫用端點，系統會採取以下動作：

• 如果懷疑出現濫用情況，系統會透過電郵向企業管理平台中列出的所有管理員發出警告
• 商家需在收到警告後的 7 天內調整其行為
• 如果在 7 天後仍未有調整呼叫使用情況，相應的手機號碼將會遭到永久停用

建議

我們建議在傳送訊息前檢查聯絡人，而在回覆所接收到的顧客訊息時則不需檢查聯絡人，因為此時您可以使用系統提供的 wa_id 立即回覆。快取結果不需要額外費用。

建立

向選擇加入對話的用戶傳送訊息之前，請向 /v1/contacts 端點傳送 POST 要求，以建立 WhatsApp 帳戶用戶驗證要求。請在呼叫中加入您想驗證的手機號碼清單。

範例

POST /v1/contacts
{
  "blocking": "wait" | "no_wait",
  "contacts": [
  	"16315551000",
  	"+1 631 555 1001",
  	"6315551002",
  	"+1 (631) 555-1004",
  	"1-631-555-1005"
  ],
  "force_check": false | true
}

您將會收到一則回應，其中包含您所要求的號碼目前之 status，以及其 WhatsApp 編號（wa_id）：

{
  "contacts": [ {
    "wa_id": "16315551000",
    "input": "16315551000",
    "status": "valid"
  },
  {
    "wa_id": "16315551001",
    "input": "+1 631 555 1001",
    "status": "processing" # Only applicable when request is non-blocking
  },
  {
    "input": "6315551002",
    "status": "invalid"
  },
  {
    "input": "+163155588",
    "status": "failed"
  }
}

找出傳回 status 為 valid 的手機號碼，儲存其 WhatsApp 編號。擁有 WhatsApp 帳戶的用戶便是有效的用戶。使用 WhatsApp 編號傳送訊息和通知。

定期重覆這些步驟，以管理您的有效用戶名單。系統會將結果快取於 WhatsApp Business 企業內部 API 用戶端資料庫 7 天。

參數

系統為向 /v1/contacts 發出的 POST 呼叫支援下列參數：

關係連線

以下關係連線連接至此節點：

封鎖

若是 blocking 參數，您有以下兩個選項：no_wait 和 wait。如果呼叫未有指定 blocking 參數，則此參數將預設為 no_wait。

由 blocking 參數決定要求是否應等待（同步）或不等待（非同步）處理完成。

手機號碼格式

contacts 要求中的手機號碼可以採用任何可撥打格式。

以下範例示範了這個做法，當中假設您使用印度手機號碼註冊了 WhatsApp Business 內部部署 API 用戶端（即國碼／區碼為 +91）：

傳回的欄位

contacts 回應裝載包含的手機號碼陣列，與內含 input、status 和 wa_id 屬性的要求中所傳送的手機號碼陣列相同：

除了 processing 狀態外，您也會看到 200 OK 的 HTTP 狀態。

如果向沒有 WhatsApp 帳戶的手機號碼傳送範本訊息，您將收到一則指出「用戶無效」的錯誤訊息，錯誤代碼為 1013。

如果回應中有任何錯誤，請參閱錯誤和狀態訊息以了解更多資訊。

封鎖聯絡人

封鎖可以視作一種防衛功能，能阻止有心人士繼續做出有害行為。您只能封鎖最近 24 小時內曾向您傳送訊息的聯絡人。

範例

傳送 API 呼叫至 /v1/contacts/{phone_number}/block，其中附上封鎖其他 WhatsApp 帳戶的原因。

POST /v1/contacts/+16315551000/block
{
   "reason": "Optional string(0;60). Freeform block reason. Will be used when another WhatsApp account is being blocked"
}

成功的回應帶有 HTTP 狀態 200，而且沒有「錯誤」物件。

失敗的話，回應看起來會是這樣：

{   
    "errors": [
        {
            "code": 2048,
            "title": "Not engaged contact",
            "details": "Invalid Request. This contact hasn't engaged with you in the last 24 hrs."
        }
    ]
}

參數

系統為向 /v1/contacts/{phone_number}/block 發出的 POST 呼叫支援下列參數：

解除封鎖聯絡人

傳送此呼叫以解除封鎖聯絡人

範例

傳送 API 呼叫至 /v1/contacts/{phone_number}/unblock

POST /v1/contacts/+16315551000/unblock

成功的回應帶有 HTTP 狀態 200，而且沒有「錯誤」物件。

失敗的話，回應看起來會是這樣：

{   
    "errors": [
        {
            "code": 1009,
            "title": "Parameter value is not valid",
            "details": "Provided WhatsApp ID is not valid. Please provide a valid WhatsApp ID or a phone number with a country code"
        }
    ]
}

參數

系統為向 /v1/contacts/{phone_number}/unblock 發出的 POST 呼叫支援下列參數：

封鎖名單

獲取已封鎖聯絡人名單的方式。

範例

傳送 API 呼叫至 /v1/contacts/blocklist，以接收有關已封鎖聯絡人的分頁名單

GET /v1/contacts/blocklist?limit=10&offset=0

您將收到回應，其中包含一頁剔除名單及分頁資訊

{
   "contacts": [
       {
           "wa_id": "16315551000@s.whatsapp.net"
       }
   ],
   "pagination": {
       "limit": 10,
       "offset": 0,
       "total": 1
   }
}

參數

系統為向 /v1/contacts/blocklist 發出的 GET 呼叫支援下列參數：

舉報

舉報提供重要訊號，以幫助建立針對有心人士的預防性解決方案。您只能舉報最近 24 小時內曾向您傳送訊息的聯絡人。

範例

如果您要封鎖其他 WhatsApp 帳戶，請傳送 API 呼叫至 /v1/contacts/{phone_number}/report，並在當中加入封鎖原因。

POST /v1/contacts/+16315551000/block
{
   "reason": "Optional string(0;60). Freeform block reason. Will be used when another WhatsApp account is being blocked",
   "block": "true | false optional boolean with default of false",
   "message_id": "message-id. Optional reported message id"
}

成功的回應帶有 HTTP 狀態 200，而且沒有「錯誤」物件。

失敗的話，回應看起來會是這樣：

{  
    "errors": [
        {
            "code": 2048,
            "title": "Not engaged contact",
            "details": "Invalid Request. This contact hasn't engaged with you in the last 24 hrs."
        }
    ]
}

參數

系統為向 /v1/contacts/{phone_number}/report 發出的 POST 呼叫支援下列參數：