联系人

/v1/contacts

使用 contacts 节点在发送消息之前对用户进行验证以管理您数据库中的 WhatsApp 用户，并使用身份哈希值验证用户的身份。

通过使用 contacts 节点，您可以：

• 验证您数据库中的电话号码是否属于有效的 WhatsApp 帐号。在向用户发送消息前，您必须确保 status 为 valid。
• 获取电话号码的 WhatsApp 编号。发送消息和用户通知都需要 WhatsApp 编号。

准备工作

您必须向客户提供订阅选项，以便在 WhatsApp 上与您的公司通讯。该订阅流程由您的公司维护。在客户订阅后，使用 contacts 节点来验证注册号码。如需了解更多信息，请参阅了解如何获得用户选择接收 WhatsApp 消息的许可。

限制

• 使用此端点可验证公司数据库中的电话号码是否属于有效的 WhatsApp 帐号
• 调用此端点的次数不能超过此电话号码所发送消息的数量

政策执行

如果公司滥用此端点，系统将执行以下操作：

• 如果公司存在疑似滥用行为，系统将通过邮件向商务管理平台中列出的所有管理员发送初始警告
• 在公司收到警告后，系统将提供七天时间让其整改不当行为
• 如果七天后公司仍未整改不当调用行为，系统将永久禁用该电话号码

建议

我们建议您在发送消息前检查联系人，但在回复传入的客户消息时则不必检查联系人，因为您可以使用提供的 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"
  }
}

保存返回 validstatus 的电话号码的 WhatsApp 编号。有效用户即拥有 WhatsApp 帐户的用户。使用 WhatsApp 编号发送消息和通知。

定期重复这些步骤，管理您的有效用户名单。结果会在 WhatsApp Business 本地 API 客户端数据库中缓存 7 天。

参数

向 /v1/contacts 发出的 POST 调用支持以下参数：

连线

以下连线会连接至此节点：

屏蔽

blocking 参数的选项有两个：no_wait 和 wait。如果调用中未指定 blocking 参数，则默认为 no_wait。

blocking 参数决定请求应该等待（同步）还是不等待（异步）处理完成。

电话号码格式

contacts 请求中的电话号码可以采用任何可拨号的格式。

下面是一些演示此操作的示例，其中假设用户使用印度电话号码（国家/地区代码为 +91）注册了 WhatsApp Business 本地 API 客户端：

返回的字段

contacts 响应负载中包含的电话号码数组与请求中发出的具有 input、status 和 wa_id 属性的电话号码相同：

除 processing 状态外，您应该还会看到 200 OK 的 HTTP 状态。

如果将模板消息发送到没有 WhatsApp 帐号的电话号码，您将收到一条错误消息，表示“用户无效”，错误代码为 1013。

如果响应中存在其他错误，请参阅错误和状态消息以了解更多信息。

封锁联系人

封锁可以被视为一种防御功能，用于阻止不良行为者继续施行有害行为。如要封锁联系人，对方必须在过去 24 小时内向您发过消息。

示例

向 /v1/contacts/{phone_number}/block 发送 API 调用，其中包含用于描述封锁其他 WhatsApp 帐号原因的 reason 参数。

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”对象。

失败的响应结果如下：

{   
    "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 调用支持以下参数：

解除封锁联系人

发出此调用以解除封锁联系人

示例

向 /v1/contacts/{phone_number}/unblock 发送API 调用

POST /v1/contacts/+16315551000/unblock

成功的响应将包含 HTTP 状态 200，不含“errors”对象。

失败的响应结果如下：

{   
    "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 调用支持以下参数：

黑名单

此部分介绍如何获取被封锁联系人的清单。

示例

向 /v1/contacts/blocklist 发送 API 调用，以获取封锁联系人的分页清单

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 小时内向您发过消息。

示例

向 /v1/contacts/{phone_number}/report 发送 API 调用；如果您要封锁其他 WhatsApp 帐号，其中还会包含 reason 参数。

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”对象。

失败的响应结果如下：

{  
    "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 调用支持以下参数：