欢迎查看 Twitter 客户互动操作指南，你将学习如何使用 webhook 和 REST API 端点构建一个基本的聊天机器人。在本操作指南中，你将了解创建一个有效的客户互动应用程序所需的全部知识，该应用程序能够使用欢迎消息、快速回复、自定义个人资料、媒体附件和按钮等内容。

webhook 是 Web 应用传达实时信息的一种方式。webhook 与流式传输不同，它们不需要活跃连接就可接收动态，它们也与 REST API 不同，因为你不需要投票。

自 2006 年 Twitter 推出以来，它一直是一个改变世界的消息传递平台。推文是一种向整个世界传递公共信息的方式。私信是一种私下对话的方式。在过去的几年里，我们一直在改进 Twitter 上的私信传递：

• 我们使得在私信中从时间线与他人分享公开推文变得更加容易。
• 我们将私信中的字符限制扩展到了 10,000 个字符。
• 我们使得能够接收来自任何人的私信。
• 我们简化了从推文、Twitter 个人资料，甚至从网站开始私信对话的过程。
• 我们允许在消息中与文本一起显示媒体和卡片，使得私信内容更加内容、更具吸引力。

现在，我们让私信成为一个开发者构建消息互动的更好渠道，他们构建互动来大规模地提供个性化客户体验。可通过 webhook 实时获取私信，借助 REST API 实现让对话更快、更简单的功能。

• 欢迎消息：欢迎消息让企业在人们进入私信对话时向他们表示问候并设定期望，不要求人们先发送一条消息。企业可以创建几条欢迎消息，并从推文、网站或应用中直接深度链接到特定的问候语。
• 快速回复：快速回复让企业以最佳方式提示人们回复私信，无论是否从选项列表中进行选择。
• 自定义个人资料：覆盖消息中附带的 Twitter 个人资料头像和显示名称，使人类元素或聊天机器人体验更加个性化。
• 按钮：将按钮附加到消息上，使人们可以轻松地在私信对话之外进行操作，比如撰写一条推文、关注某个账号，或者在 Twitter 应用中打开一个网站。

为了获得构建良好客户体验所需的消息，你将需要：

• 创建一个具有正确权限的 Twitter 应用，以便能够通过 API 从 Twitter 账号接收动态（包括私信）。
• 通过 Twitter 登录使用 OAuth 来获得使用客户私信的权限
• 配置一个 webhook 来订阅用户动态并获取所需的消息

若要通过在私信中回复收到的消息和使用你可能需要的新功能来创建体验：

• 使用欢迎消息 REST 端点创建和管理欢迎消息
• 使用 REST 端点将快速回复和自定义个人资料附加到消息和欢迎消息中
• 使用 REST 端点将媒体添加到对话中
  

作为开发者，你需要执行几个步骤来开始使用私信服务。

• 在你批准的开发者账号的“应用”页面上创建一个应用。如果你要代表你的公司创建应用，推荐使用 Twitter 公司账号进行创建。
• 在应用页面的 permissions 选项卡上启用“Read, Write and Access direct messages”。
• 在“Keys and Tokens”选项卡上，记下应用的使用者密钥（API 密钥）和使用者令牌（API 机密）。
• 在该选项卡上生成应用的访问令牌和访问令牌机密。你将需要这些访问令牌来注册你的 webhook URL，这是 Twitter 将发送账号事件的地方。
• 如果你不熟悉 Twitter 登录，而且不熟悉用户情景如何用于 Twitter API，请查看获取访问令牌。当你添加要接收事件的账号时，你将使用该账号的访问令牌来订阅它们。
• 记下应用的数字 ID，如开发者门户的“应用”页面中所示。当你申请账号动态 API 访问权限时，你将需要此应用 ID。
  

创建 Twitter 应用后，下一步就是申请账号动态 API 访问权限。

要访问沙盒或付费高级账号动态 API 层级，你需要设置一个开发者账号。如果你还没有申请开发者账号，请通过以下链接进行申请：

申请开发者账号

拥有开发者账号后，你就可以设置对高级账号动态 API 的访问。你将需要一个 Twitter 应用来附加到账号动态 API 开发环境。

1. 登录并导航到“Dev Environments”页面。 
2. 单击“Set up dev environment”，为环境命名，并为环境指定一个 Twitter 应用 ID。你选择的环境名称将取代我们的高级端点 URL 示例中的 :env_name 令牌。例如，如果你使用环境名称“prod”，URL 模式将是https://api.twitter.com/1.1/account_activity/all/prod/webhooks。
    

如果你想使用带有可视化面板的脚本来设置账号动态，你应该查看 Twitter 开发支持的账号动态面板。

• 收到账号动态 API 访问权限后，你需要开发一个将接收 Twitter webhook 事件的 Web 应用，并进行部署和托管。 
• 创建一个带 URL 的 Web 应用，作为 webhook 来接收事件。这是部署在服务器上的端点，用于侦听传入的 Twitter webhook 事件。 
  • URI 路径完全由你决定。此示例有效：https://mydomain.com/service/listen
  • 如果你要侦听各种来源的 webhook，常见的模式是：https://mydomain.com/webhook/twitter
  • 请注意，指定的 URL 不能包含端口规范 (https://mydomain.com:5000/NoWorkie)。
• 正如保护 webhook 指南中所述，第一步是编写代码，它用于接收 Twitter 挑战响应检查 (CRC) GET 请求，并以正确格式的 JSON 响应。 
• 注册 webhook URL。你将向 /webhooks.json?url= 端点发出 POST 请求。在你发出此请求时，Twitter 将向你的 Web 应用发出一个 CRC 请求。成功注册 webhook 后，响应将包含一个 webhook ID。以后向账号动态 API 发出一些请求时需要使用该 webhook ID。 
• Twitter 将向你注册的 URL 发送账号 webhook 事件。请确保你的 Web 应用支持对传入事件的 POST 请求。这些事件将用 JSON 进行编码。请查看此处，了解 webhook JSON 有效负荷示例。
• Web 应用准备好后，下一步就是添加账号来接收动态。添加（或删除）账号时，你将发出引用账号 ID 的 POST 请求。请查看我们的订阅添加指南，了解更多信息。
• 要验证你的应用和 webhook 是否配置正确，请对应用订阅的某个 Twitter 账号发布的推文点赞。对于你的订阅者收到的每一篇收藏文章，你可通过向你的 webhook URL 发送 POST 请求来接收收藏夹事件。

若要代表其他账号执行撰写操作（创建推文或消息），或者阅读该账号中的私人信息，你需要获得访问令牌。使用 Twitter API 时，访问令牌会提供用户情景。

• 用户 - 一名 Twitter @用户。Twitter API 上的所有撰写操作都需要用户情景。聊天机器人在 Twitter 账号上，并不是自己的实体。聊天机器人所在的账号就是一名用户。与聊天机器人互动的客户也是用户。在 Twitter 上发送的消息都是在两个用户实体之间传递的。
• 应用 - 在你批准的开发者账号中创建的一个 Twitter 应用。一个应用始终由一位用户拥有。应用提供了使用 Twitter API 的基本情景。
  

1. 用户拥有应用/单个用户 - 如果用户是应用的所有者，他们可以访问开发者门户的“应用程序”页面，在应用“详细信息”部分中的“Keys and Tokens”选项卡上生成访问令牌。点击页面底部的“Create”按钮。
2. 用户没有应用/多名用户 - 如果你的应用要代表多位用户使用账号动态事件，每位用户必须向你的应用验证以授予权限。要实现此目的，你必须拥有一个实现 Twitter 登录的 Web 应用。

此时在该过程中，你应该拥有在开发者门户设置应用程序所需的全部信息，执行初始的挑战响应检查来保护你的端点，并获取访问令牌，以便在你自己的应用程序上以及代表已获得明确权限的其他人发布内容。现在，让我们来看看我们将在应用中使用的不同端点。

为了提供对话式的体验，我们通过 webhook 实时提供私信数据，其中包括该体验中功能的元数据。此外，我们还有 REST 端点来创建消息，获取欢迎消息和自定义个人资料数据，并管理这些功能。理解下面的基本流程将有助于你根据步骤 3 中克隆的示例应用设置自己的应用。

• 有关私信（发送和接收的私信）的数据通过开发者的账号动态 API webhook 设置实时提供给开发者
  • 为应用注册一个 webhook URL：
    • POST account_activity/all/:env_name/webhooks 的 API 调用
    • 开发者在每个环境中只能注册 1 个 URL
  • 开发者会要求用户通过 Twitter 登录对应用进行授权，以生成有效的访问令牌。
  • 添加一个新的订阅（使应用能够代表用户通过注册的 webhook 接收私信）
    • POST account_activity/all/:env_name/subscriptions 的 API 调用
    • 用户需要有应用的有效访问令牌（步骤 4）
  • 使用 PUT account_activity/all/:env_name/webhooks 端点验证你的 webhook URL
  • 使用 GET account_activity/all/:env_name/webhooks 端点检索你的 webhook 配置
• 使用 GET direct_messages/events/list 端点获取过去 30 天内发送和接收的所有私信
• 使用 GET direct_messages/events/show 端点根据 ID 获取单个私信，此端点没有时间限制
• 使用 POST direct_messages/events/new (message_create) 发送消息
  
  • 此处的 send-direct-message 脚本中引用了该端点
    

• 使用 POST direct_messages/welcome_messages/new 创建一条新的欢迎消息
  • 此处的 create-welcome-message 脚本中引用了该端点
• 使用 POST direct_messages/welcome_messages/rules/new 为欢迎消息创建一条新规则
  • 此处的该脚本中引用了该端点

• 使用 DELETE account_activity/webhooks/:webhook_id/subscriptions 删除订阅
  • 该脚本中引用了此端点
• 使用 GET account_activity/webhooks 获取当前的 webhook 配置
  • 该脚本中引用了此端点

下面是一个调试工具列表，你在构建应用程序时可能会发现它很有用：

• Postman - 构建模拟请求
• Ngrok - 在本地计算机上测试代码
• Runscope - 让开发者员能够看到 API 流的工作方式

现在你已经创建了一个解决方案，可实时访问私信，并代表客户大规模地创建个性化体验。你可以用一条欢迎消息开启对话来设定情景。你可以撰写具有快速回复选项、链接打开按钮或附加有趣媒体内容的消息。这些消息可以有一个自定义个人资料，明确指出真人或聊天机器人何时在进行互动。理想情况下，它如该示例所示。

借助此功能，开发者可在任何私信或欢迎消息 POST 请求中最多添加 3 个行动号召或按钮。按钮可用于打开任何 https URL，Twitter 应用中向用户显示的行动号召可以完全自定义。

按钮的目的是让用户更容易完成私信之外的操作，无论是在 Web 视图还是在 Twitter 应用的其他部分。例如，CTA 可以用来：

• 在私信互动结束时撰写一条推文，例如，向其他人介绍一个聊天机器人，或公开分享优惠券或报价。这可以使用推文网络意图 URL 方案来实现。
• 在私信互动结束时关注一个用户账号，例如，作为企业在互动结束时的最后请求。这可以使用关注按钮网络意图 URL方案来实现。
• 向不同的账号发送私信，例如将用户从与营销相关的聊天机器人引导到专门的客服 @username，以获得相关人员的帮助。这可以使用私信深层链接方案 (twitter.com/messages/compose…) 来实现。
• 打开 Web 视图与移动网站页面进行交互，这比在消息中完成该动作更适合，例如完成信用卡购买或与不同产品的并列比较进行交互。

有关按钮的技术信息，可查看此处。