WhatsAppBusiness官方说明导读及调研分析

1. WhatsAppBusiness是什么

官方描述为：通过 WhatsApp Business API，大中型企业可与客户进行大规模通信。企业可使用此 API 来构建系统，将数千名客户与客服人员或智能助手连接起来，实现程序化交流和人工交流。此外，您还可将此 API 与众多后端系统集成，如 CRM 和营销平台。

从官方的描述来看WhatsAppBusiness围绕消息展开，同时API要兼顾外部系统集成的易用性，并且配套相关API、后台（WABA后台、BSP后台）、其他支持（例如，业务工单、本地到云迁移支持、webhook server压测指导支持等），总体来看，即使已经具备了类似的IM通道能力，但想要完全复制一个WhatsAppBusiness建设成本会仍然会较大，前期可以考虑从其某些模块进行切入。

此外，有意使用此 API 的企业可以选择两种托管方式：本地 API 和云端 API。

• 云端 API
  云端 API 允许您使用 Meta 所有的云端服务器向客户发送消息及接收客户消息。由于我们托管 API，您可以省去托管自有服务器的成本，并且可以轻松地增加业务消息互动量。
• 本地 API
  本地 API 允许您使用自有服务器向客户发送消息及接收客户消息，可以把本地API理解为一个基于docker部署的开箱即用的完整应用。包括服务本身及DB，DB支持Mysql、PostGreS（业务数据和配置保存在DB中）。同时配套了完整的设置、监控、伸缩、日志等配套体系方便集成方使用。通过这样的方式在自己的服务器上托管本地 API。
• 本地 API与云端 API对比
  详见：https://developers.facebook.com/docs/whatsapp/cloud-api/overview#—api-----api----
  从对比和之前调研分析来看，本地 API 最大好处是可以获得较高的吞吐量（官方也提供了本地API的扩容指导）；另外就是私有部署所带来的相关好处（非消息类的业务数据本地私有存储）。

2. WhatsAppBusiness概述（overview）

• 版本管理
  官方描述为：每个版本大约可用 2 年，然后将停用并无法再受到调用。其意图为：为了确保开发人员和企业在使用API时保持最新和安全的状态。随着时间的推移，WhatsApp将推出新版本的API来添加新功能、解决漏洞和改进性能，以确保API的稳定性和可靠性。停用旧版本的API可以鼓励开发人员和企业使用新版本的API，并且可以使WhatsApp更容易维护和更新API。另外，由于WhatsApp Business API涉及到用户数据和隐私问题，因此限制旧版本的使用还可以有助于确保数据的安全性和保护用户的隐私。建议开发人员和企业在API版本停用之前尽早升级到最新版本，以确保API的可用性和业务的正常运作。

• 吞吐量
  在默认情况下，云端 API 支持的每秒收发文本消息和媒体消息的总量最多为 80 条，但企业可以请求将此上限提升至 500 条。方式为：给官方提工单。

• 流量限制
  流量限制是指应用或用户在指定时间段内可以发出的 API 调用次数。如果超过此上限，或超过 CPU 的承载范围或总次数上限，则系统可能会对应用或用户采取节流措施。遭到节流的用户或应用发出的 API 请求将失败。官方的描述大致可以认为基于频度和并发两个维度去流控。

• 可用指标
  作为云端 API 用户，您可以查看已发送和已送达的消息数量。由于计费策略和会话强相关，因此提供消息和会话数量的相关查询能力十分必要。

• 扩展
  在 Meta 的基础架构中，云端 API 会在您的流量限制（消息量和 WhatsApp Business 商业帐号的数量）内自动扩展并调整，以处理您的工作负载。估计WhatsAppBusiness云服务端使用类似k8s机制实现了动态扩缩容。

• 数据隐私和安全
  消息传输采用加密传输方式，本质是一个端到端的加密方案，详见：https://developers.facebook.com/docs/whatsapp/cloud-api/overview/data-privacy-and-security

• 加密
  API 使用图谱 API 来发送消息，使用 Webhooks 来接收事件，两者均采用业界标准 HTTPS 运作，受 TLS 保护。Http的东西采用Https这是废话。

3. WhatsAppBusiness入门指南（get-started）

3.1 设置开发者资产和开放平台访问权限

按照官方的3步可以成功创建一个商业账户（WABA：WhatsApp Business Account）：注册成为 Meta 开发者、为帐户启用双重验证、创建 Meta 应用，其中双重验证为可选选项。另外WABA创建成功之后可以进行商户认证，认证成功后会一个绿标，用户即可知道该商家是经过官方认证的可信商家。

3.2 发送测试消息

如果要通过API去发消息，首先需要搞定API鉴权。获取token的方式如下：

### 请求（获取短期Token）
https://graph.facebook.com/v16.0/oauth/access_token?client_id={appId}&client_secret={appSecret}&grant_type=client_credentials

##应答
{
  "access_token": "{tokenValue}",
  "token_type": "bearer"
}

1、client_id和client_secret在WABA后台中查看。
2、返回值中的token_type从命名上看token_type，就是基于OAuth 2.0中的Bearer Token和MAC Token。

发消息的示例为：

### 文本消息
POST https://graph.facebook.com/v16.0/FROM_PHONE_NUMBER_ID/messages
Authorization: {tokenValue}
Content-Type: application/json

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "{whatsAppId}",
  "type": "text",
  "text": {
    "preview_url": false,
    "body": "MESSAGE_CONTENT"
  }
}

WhatsApp Business API 的消息发送接口中，to 参数需要填写接收者的 WhatsApp 号码，具体获得 WhatsApp 号码的方式如下：

1. 用户自己提供：用户可以主动告诉您他们的 WhatsApp 号码，然后您可以在 API 调用时填写该号码。
2. 通过 WhatsApp Link 获得：用户可以通过发送他们的 WhatsApp 链接来分享他们的 WhatsApp 号码。当您收到链接时，可以点击链接并3在浏览器中打开，然后会跳转到 WhatsApp 应用程序并显示用户的号码。
3. 通过 WhatsApp 二维码获得：用户可以生成他们的 WhatsApp 二维码并分享给您。您可以使用智能手机上的 WhatsApp 应用程序扫描该二维码，然后在 API 调用中填写该号码。

需要注意的是，由于 WhatsApp Business API 是面向企业的，因此您需要事先获得用户的许可才能向其发送消息。此外，您也需要与 WhatsApp 合作伙伴或提供商合作并进行相关配置才能开始使用 WhatsApp Business API。

3.3 配置 Webhooks

Webhooks在整个WhatsAppBusiness中占用非常重要的作用，可以说它是WhatsAppBusiness向外发送通知、对外数据同步、对外系统集成的关键，官方描述：如果想在收到消息或消息状态变更时收到提醒，则需要为应用设置 Webhooks 端点。Webhooks不限于通常理解的消息路由，从后台来看可以订阅很多对象，例如：

• 用户专用 Webhooks
• 广告帐户专用 Webhooks
• 证书透明度专用 Webhooks
• Instagram 专用 Webhooks
• 线索专用 Webhooks
• Messenger 专用 Webhooks
• 公共主页专用 Webhooks
• 支付专用 Webhooks
• WhatsApp 专用 Webhooks

管理后台中显式的订阅对象和文档中不完全一致，推测可能是不同类型的商家所支持的订阅对象集合是不一样的。另外大概率Webhooks的配置并不是在某一个后台中统一收拢的，从后续的调研来看使用WhatsApp Business至少会涉及2个后台：一个WABA后台，一个BSP（Business Service Provider，后台再说BSP以及BSP、WABA、Product之间的关系）后台。

另外，Webhooks有签名机制：我们使用 SHA256 签名来签署所有事件通知负载，并在请求的 X-Hub-Signature-256 标头中添加签名，而且会在前面加上 sha256=。验证负载并非强制要求，但我们建议您这样做。这是一个安全问题，在很多开放平台中对外的通知或者路由一般都是会加签名的。

• Webhooks 送达失败
  官方描述：“如果我们向您的端点发送 Webhooks 请求，而您的服务器返回除 200 以外的 HTTP 状态代码，或者如果 Webhooks 由于其他原因而无法送达，我们将以较低的频率继续尝试发送请求，直到请求发送成功，重试操作最多持续 7 天”。低频持续N天的重试策略较好，它可以解决每隔多少时间，最多重试N次的重试仍然失败问题。

• IP 地址
  官方描述：“您可以通过在自己的终端运行以下命令，获取我们 Webhooks 服务器的 IP 地址，我们会定期更改这些 IP 地址，因此如果您将我们的服务器加入白名单，您可能需要不定期重新生成此命令并相应地更新您的白名单”。从网关出入访策略来说，出于安全保障还是必要的。

3.4 接收测试消息

官方描述：“现在您的 Webhooks 已设置完毕，请向您使用的测试号码发送一条消息”。

3.5 订阅

官方描述：“您需要获得用户的订阅许可，才能主动发送商家发起的消息”。这非常必要，因为能从游戏规则上避免了商家不能主动的对客户进行消息骚扰。可以类比微信公众号，只要用户关注了某个公众号，公众账号才能给其用户推送消息，而不是说，我注册了一个公众号之后就能想给谁发就给谁发。

3.6 定价和支付方式

1、根据对话向商家收费，其中包括 24 小时会话期内送达的所有消息。
2、每月前 1,000 次对话免费
3、基于信用卡扣费。

备注：

• 2022年2月1日前WhatsApp Business API 收费模式是「基于通知的定价 Notification-Based Pricing」；从2022年2月1日开始就会变成「基于对话的定价 Conversation-Based Pricing」对于使用 WhatsApp Business 开放平台的商家，我们会根据对话向商家收费，其中包括 24 小时会话期内送达的所有消息。如果企业想向客户传送讯息并开始一个新的24小时对话，企业就只能传送「模板消息」作为第一则起始讯息。
• 免费策略不仅仅如此，例如：免费接入点对话，当用户使用 WhatsApp 直达广告中的行动号召按钮或 Android/iOS 设备上的 Facebook 公共主页行动号召按钮向商家发送消息时，不会收取对话费用 。

3.7 发送更多消息

官方描述：“若要发送更多商家发起的消息，则需要使用消息模板”。

不理解，没有哪里看到模板消息免费，也没有看到说模板消息便宜。之前的调研结果是基于会话计费，会话的最大生命周期为24小时，从这些来看也看不出使用模板消息能免费或者便宜。非官方解释：WhatsApp Business 允许商家使用标准消息，而这些消息通常不会产生额外费用。标准消息是指商家向客户发送有关交易和订单的信息，例如确认订单和更新订单状态等。因此推测：双向的才被认为是一个会话，单向的商家->用户的通知之类的不被认定为一个会话，也就不计费。

3.8 Add a Phone Number

一个手机号码要么注册个人WhatsApp，要么注册WhatsApp business商业账号，不能同时共存。

3.9 Migrate an Existing WhatsApp Number to a Business Account

1、实测WhatsApp与WhatsAppBusiness之间消息互通（谁都可以向对方进行消息收发）
2、WhatsApp与WhatsAppBusiness来回切信息也不会丢失（会话数据，设置数据等）。
3、WhatsAppBusiness多一个商家的Tab页。有可能WhatsAppBusiness和WhatsApp可以认为是同一个东西多包名，例如：滴滴的司机端和用户端其实都是1个滴滴APP。不过也不排除基于一些历史原因，WhatsApp和WhatsAppBusiness就是两个APP。

3.10 业务解决方案提供方入门指南

主要描述如何把本地API迁移到云API，一般不会涉及。

4. 参考和指南（reference & guides）

首先需要说明的是：老外写API文档和我们不一样，我们往往会在一个地方先写API定义然后再给API调用示例，老外会写到两个地方，先在guides部分给出示例，然后在reference里详细说明每个参数的描述。因此这里我合起来一起介绍吧。

4.1 账户集成（Account Migration）

主要是说本地API -> 云API之间迁移，由于一般不涉及本地API，因此不详细介绍。入有需要详见：https://developers.facebook.com/docs/whatsapp/cloud-api/reference/account-migration

4.2 商户信息（Business Profiles）

商户信息包含以下字段：

• about
• address
• description
• email
• messaging_product
• profile_picture_url
• vertical：商家类型，例如：EDU，HOTEL，HEALTH……
• websites

1、获取商户信息
接口支持指定返回哪些字段，示例如下：

curl \ 
'https://graph.facebook.com/v16.0/FROM_PHONE_NUMBER_ID/whatsapp_business_profile?fields=about,address,description,email,profile_picture_url,websites,vertical' \
-H 'Authorization: Bearer ACCESS_TOKEN'

2、设置商户信息
接口支持Key(fieldName)-Value(filedValue)方式进行设置，示例如下：

curl -X POST \
  'https://graph.facebook.com/v16.0/PHONE_NUMBER_ID/whatsapp_business_profile' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "messaging_product": "whatsapp",
    "about": "ABOUT",
    "address": "ADDRESS",
    "description": "DESCRIPTION",
    "vertical": "INDUSTRY",
    "email": "EMAIL",
    "websites": [
      "https://WEBSITE-1",
      "https://WEBSITE-2"
    ],
    "profile_picture_handle": "HANDLE_OF_PROFILE_PICTURE"

3、删除商户
官方原文：“To delete your business profile, you must delete your phone number”，这里因该理解为商家注销，如果只想把某个Profile字段值空，可以使用修改接口。

4.3 媒体（Media）

这里的媒体可以理解为文件服务相关，可以类比OSS。
1、上传媒体 Upload Media

curl -X POST 'https://graph.facebook.com/v16.0/<MEDIA_ID>/media' \
-H 'Authorization: Bearer <ACCESS_TOKEN>' \
-F 'file=@"2jC60Vdjn/cross-trainers-summer-sale.jpg"' \
-F 'type="image/jpeg"' \
-F 'messaging_product="whatsapp"'

2、获取媒体 Retrieve Media URL

curl -X GET 'https://graph.facebook.com/v16.0/<MEDIA_ID>/' \
-H 'Authorization: Bearer <ACCESS_TOKEN>'

3、删除媒体Delete Media

curl -X DELETE 'https://graph.facebook.com/v16.0/<MEDIA_ID>' \
-H 'Authorization: Bearer <ACCESS_TOKEN>'

4、下载媒体 Download Media

curl  \
 'URL' \
 -H 'Authorization: Bearer ACCESS_TOKEN' > media_file

备注：与Retrieve Media的差别是一个基于文件，一个是基于字节流（Download Media）。

5、支持媒体类型Supported Media Types
描述支持哪些媒体类型，这是一个安全问题，但是没有实测WhatsAppBusiness是否基于了头文件验证，还是说只是简单的验证文件的扩展名。

4.2 消息（Message）

WhatsAppBusiness消息类型有以下三种，但是需要特别说明的是：一般消息、互动消息、模板消息3种消息类型可以任意组合，例如：Text-Based Message Templates、Media-Based Message Templates、Interactive Message Templates，下面对这三种消息类型分别给予介绍：

• 一般消息
  可以认为一些常用的文本和富文本消息都可以认为是一般消息，例如：文字、图片、影片、档桉、语音、贴图等。发送文本消息示例如下，其他类型的消息发送示例参考：https://developers.facebook.com/docs/whatsapp/cloud-api/guides/send-messages

curl -X  POST \
'https://graph.facebook.com/v16.0/FROM_PHONE_NUMBER_ID/messages' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '
    {
      "messaging_product": "whatsapp",
      "recipient_type": "individual",
      "to": "PHONE_NUMBER",
      "type": "text",
      "text": { // the text object
        "preview_url": false,
        "body": "MESSAGE_CONTENT"
        }
    }'

需要说明的是消息发送成功后，应答会给出消息ID，并且官方提供根据消息ID修改消息已读状态的接口，例如：

curl -X POST \
'https://graph.facebook.com/v16.0/PHONE_NUMBER_ID/messages'
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
  "messaging_product": "whatsapp",
  "status": "read",
  "message_id": "MESSAGE_ID"
  }'

• 互动消息（Interactive Message）
  互动式讯息 (Interactive Message) 有两种类型 —— 列表讯息 (List Message) 及回覆按钮 (Reply Button)。这个功能需要配合自动聊天机器人（Chatbot）使用，即是互动式讯息只能chatbot事先设定好，当企业收到特定的讯息关键字时，就会触发chatbot向顾客回覆设定好的互动式讯息。在自动聊天机器人内，这两种互动式讯息可以在一组流程内同时使用，但用户每次只能选择一个选项，例如：

[user]     Hello! l learned about your sevices from your offical website and want to get more!
[servcie]  Hello! I'm XXX, XXX's chatbot glad to assit u, How can i help u ?
            * XXX features
            * Pricing Plan
            * Human Agent

• 模板消息（TemplateMessage）
  使用模板消息事先得到WhatsApp批准使用的模板信息，参考:https://developers.facebook.com/docs/whatsapp/message-templates/creation/
  模板消息有以下3种：
  文字模板消息：只有文字的模板消息。例如：Hi John! Thanks for being our valued member from Jun 2021. We’ll send you feature updates every month to keep you informed. 对应模板为：Hi {{1}}! Thanks for being our valued member from {{2}}. We’ll send you {{3}} updates every {{4}} to keep you informed.
  媒体模板消息：带有富文本信息（图片，文件，音视频等）的模板消息。
  互动式模板消息：互动式讯息范本提供按钮让客人点击，按钮包括行动按钮和回覆按钮。

4.3 电话号码

介绍云端 API 中所用电话号码的验证方法及其格式设置要求，您需要验证向客户发送消息时要使用的电话号码。必须使用通过短讯/语音通话发送的代码验证电话号码。这里简单知道支持短信和语音（2G电话方式）两种验证方式即可。

4.4 注册

1、注册公司电话号码

curl -X POST \
  'https://graph.facebook.com/v16.0/FROM_PHONE_NUMBER_ID/register' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "messaging_product": "whatsapp",
    "pin": "6_DIGIT_PIN"
  }'

接口中不直接暴露公司电话号码，根据查到的信息做法为：通过鉴权token就知道是哪个商家，然后就能知道其注册时提供的电话号码了，因此不需要提供电话号码参数。这意味着，这个接口的作用只是确认账户电话为公司电话。6位的PIN码是一个额外安全机制详见：Two-Step Verification（两步验证），这里就是两步验证的实例：1验证了token，2验证了6位PIN码，两步验证都通过了，才是验证通过。

2、注销公司电话号码

curl -X POST \  
 'https://graph.facebook.com/v16.0/FROM_PHONE_NUMBER_ID/deregister' \  
 -H 'Authorization: Bearer ACCESS_TOKEN'

4.5 两步验证（Two-Step Verification）

一项额外的安全功能，可帮助商家保护其WhatsApp账户的安全性。它要求商家在登录WhatsApp Business时输入一个6位数的PIN码，以确保只有他们自己才能访问其账户。这项功能可以保护商家的电话号码不被未经授权的人员访问或使用。如果有人尝试登录商家的WhatsApp Business账户，系统会要求输入Two-Step Verification PIN码。如果商家没有提供正确的PIN码，他们将无法访问账户。在“注册公司电话号码”的介绍中就给了一个两步验证的实例。

4.6 WhatsApp商业账号（WhatsApp Business Accounts）

这里需要重点了解BSP、WABA概念及关系。一个BSP下可以关联多个WABA，一个BSP下可以有多个Product。
1、Business Manager
另外一个独立的商务管理平台后台，初步看有广告管理，商业主页设置，经分数据，用户管理、支付、业务信息等很多经营相关管理工具，但是它与商业号开发者后台不是一体，而是彼此独立的2个后台。从功能上看，这个后台是商家日常经营所经常需要使用的。个人理解可以把其认为是BSP后台，而商业号开发者后台即WABA后台。

2、During Embedded Signup Onboarding
嵌入式注册，大致的做法是通过Webhook，WhatsApp对外发送 Facebook 登录回调并会将企业的 WABA（WhatsApp Business Account）分享给相应 BSP（Business Service Provider）。

3、Getting all WABAs shared with your business
可以把一个BSP认为是一个企业，一个企业下可以通过WABAs shared的方式对应多个 WABA。然后BSP具备一些较大的权限，例如：创建消息模板、为帐户分配用户、查看支付信息、查看访问指标等。可以类比：太平洋产险（BSP）下可以有太平洋产险北京分公司（BSP下的其中一个WABA）。

QA：同一个BSP下的不同WABA可以直接经营该BSP下所有Product？
在WhatsApp Business中，同一个BSP下的不同WABA可以直接经营该BSP下所有Product吗？

在WhatsApp Business中，BSP是指Business Solution Provider，而WABA是指WhatsApp Business Account。

如果在同一个BSP下有多个WABA，它们可以经营该BSP下的所有产品，但前提是这些产品已经被该BSP所支持和授权。也就是说，BSP需要先向WhatsApp申请授权来支持某些产品，然后它所管理的所有WABA才能够经营这些产品。

因此，即使有多个WABA在同一个BSP下，它们也只能够经营那些已被BSP授权的产品。如果某个WABA想要经营另外一种产品，那么它所属的BSP就需要先向WhatsApp申请相应的授权，然后该WABA才能够开始经营这个新产品。

5 总结

本文只是一个导读，详细还请了解官方文档。不过大致上来说，可以把WhatsApp类比为国外的微信，WhatsAppBusiness则可以类比为微信企业/公众号 + 淘宝，再结合facebook本身的社交功能，可以说facebook整合了社交＋微信＋淘汰，不得不佩服人家的战略布局和整合能力。

---

原创不易，请给作者打赏或点赞，您的支持是我坚持原创和分享的最大动力！