聯絡人

/v1/contacts

使用 contacts 節點來管理資料庫中的 WhatsApp 用戶，方法是在向他們傳送訊息之前對其進行驗證，並使用身分雜湊來驗證用戶的身分。

透過 contacts 節點，您可以：

• 驗證資料庫中的電話號碼是否屬於有效的 WhatsApp 帳號。您必須確認 status 為 valid，才能傳送訊息給用戶。
• 取得電話號碼的 WhatsApp 編號。需要有 WhatsApp 編號，才能傳送訊息和用戶通知。

準備工作

您必須提供選項，讓顧客選擇是否要與商家進行 WhatsApp 通訊。這個選擇接收訊息的流程是由商家維護。在顧客選擇接收訊息之後，請使用 contacts 節點來驗證註冊的電話號碼。如需更多資訊，請參閱瞭解如何取得 WhatsApp 的選擇接收訊息。

限制

• 使用此端點來驗證商家資料庫中的電話號碼是否屬於有效的 WhatsApp 帳號
• 通話次數不得超過電話號碼傳送的訊息數量

政策執行

如果商家濫用端點，我們將採取以下措施：

• 如果疑似有濫用情形，企業管理平台中列出的所有管理員會透過電子郵件收到初步警告
• 商家在收到警告後有 7 天的時間可調整其行為
• 如果 7 天後未調整通話行為，電話號碼將永久停用

建議作法

建議在傳送訊息之前先檢查聯絡人，但是在回應傳入的顧客訊息時，不需要檢查聯絡人，因為您可以使用所提供的 wa_id 立即回應。快取結果不需要額外費用。

建立

在傳送訊息給選擇接收訊息的用戶之前，先傳送 POST 要求至 /v1/contacts 端點，以建立 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 狀態，您應該會看到 HTTP 狀態為 200 OK。

若將範本訊息傳送至沒有 WhatsApp 帳號的電話號碼，您會收到一則註明「用戶無效」及錯誤碼 1013 的訊息。

關於回應中的任何其他錯誤，請參閱錯誤和狀態訊息。

封鎖聯絡人

您只能封鎖過去 24 小時內曾經傳送訊息給您的聯絡人。

範例

傳送一則 API 呼叫至 /v1/contacts/{phone_number}/block，並註明封鎖其他商業帳號的原因。

POST /v1/contacts/+16315551000/block
{
   "reason": "Optional string(0;60). Freeform block reason. Will be used when another business 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 呼叫：

Blocklist

這是取得已封鎖聯絡人名單的方法。

範例

傳送一則 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 小時內曾經傳送訊息給您的聯絡人。

範例

傳送一則 API 呼叫至 /v1/contacts/{phone_number}/report，並註明封鎖其他商業帳號的原因。

POST /v1/contacts/+16315551000/block
{
   "reason": "Optional string(0;60). Freeform block reason. Will be used when another business 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 呼叫：