借助 Papo (https://papo.global/)，您可以使用 REST API 列出对话、发送文本消息、应用标签并将对话分配给坐席，无需访问界面即可自动化服务流程。API 提供的端点映射了“对话”模块的功能，让外部系统能够以编程方式管理交互。
| API 操作 | 功能 | 使用示例 |
|---|---|---|
| 列出对话 | 返回账户的对话，可按状态、标签或坐席筛选 | 从外部 CRM 监控进行中或已结束的服务 |
| 发送文本消息 | 向联系人发送文本消息（遵守 WhatsApp 24 小时窗口） | 通知客户订单更新 |
| 应用标签 | 创建标签（如果不存在）并将其应用到联系人和打开的对话 | 自动将对话标记为“紧急”或“售后” |
| 分配对话 | 将某个联系人的打开对话分配给指定坐席 | 将线索分配给负责该区域的销售 |
Papo 对话 API 的工作原理
Papo API 遵循 REST 标准，通过密钥（Bearer token）进行身份验证，并以 JSON 格式返回响应。本文所述的所有操作都使用相同的身份验证基础，并可组合起来创建自动化工作流——例如，一个分流系统在收到新线索时，列出最近的对话、应用“新”标签并分配给值班坐席。
API 的基础地址为 https://app.papo.global/api/v1。要使用对话、标签和分配端点，您需要在 Papo 面板中生成 API 令牌。包含具体端点和参数的完整文档见 papo.global/pt/docs。
使用 API 资源的分步指南
1. 生成 API 令牌
在 Papo 面板中，进入开发者或访问令牌部分。创建一个具有管理对话适当权限的密钥（sk_live_…）。请将令牌保存在安全位置——它将在所有请求的 Authorization 请求头中发送。
2. 列出对话
使用对话列表端点获取账户的服务记录。该请求接受筛选参数，例如：
- 状态：打开的、已结束的或全部对话。
- 标签：按一个或多个已应用标签筛选。
- 坐席：限制为分配给特定用户的对话。
- 时间段：用于限制查询的日期范围。
响应包括对话标识符、联系人、渠道、状态和最近消息。借助这些数据，您可以监控服务量，或从外部系统触发条件操作。
3. 发送文本消息
要向联系人发送文本消息，请使用消息发送端点。该请求要求：
- 收件人号码，采用国际格式（例如
5511999999999）。 - 消息文本。
- 实例标识符（可选）——如果您的账户有多个 WhatsApp 连接，可以指定要使用哪一个。
API 会返回请求已接受的确认。请记住，发送文本消息受 WhatsApp 24 小时窗口限制；对于该时间段之外的通信，需要使用预先批准的模板消息（HSM）。
4. 为联系人和对话应用标签
API 允许通过两种方式管理标签：
- 在账户中创建标签：为新标签定义标题、颜色和描述。
- 应用标签：将现有标签关联到联系人和该联系人的打开对话。如果标签尚不存在，则会在应用过程中自动创建。
这对于根据您系统的规则自动分类对话非常有用——例如，当客户发送特定关键词时标记为“投诉”。
5. 将对话分配给坐席
使用分配端点，您可以为某个联系人的所有打开对话指定一名坐席。只需提供联系人标识符和用户/坐席 ID。账户的坐席列表可通过用户列表端点获取，该端点返回每位团队成员的姓名、电子邮件和 ID。
此功能对于自动路由至关重要：CRM 系统在识别线索画像后，可以无需人工干预将其分配给正确的销售。
谁应该使用对话 API
- 已经使用外部系统的运营团队（ERP、CRM、电商平台），希望集成 Papo 服务而不重复工作。
- 拥有复杂路由规则的支持团队，需要根据客户数据自动分类和转接对话。
- 构建自定义仪表盘或根据服务事件触发通知的开发者。
- 管理多个账户并希望为每个客户自动配置标签和分配的白标经销商。
常见问题
我需要 API 令牌才能使用这些端点吗？
是的。所有 Papo API 请求都需要通过密钥进行身份验证，并在 Authorization: Bearer sk_live_… 请求头中发送。令牌在账户面板中生成。
API 允许在 WhatsApp 24 小时窗口之外发送消息吗？
通过 API 发送文本消息需遵守 24 小时窗口。对于该时间段之外的主动通信，需要使用已批准的模板消息（HSM）。Papo 提供用于发送 HSM 的专用端点。
我可以按标签列出对话吗？
可以。对话列表端点接受按标签筛选，让您只检索带有一个或多个特定标签的服务记录。
如何通过 API 为联系人应用标签？
使用标签端点，提供标签标识符（或用于创建的数据）和联系人标识符。标签将应用到该联系人及对应的打开对话。
API 会返回完整对话历史记录吗？
对话列表返回元数据和最近消息。要获取特定对话的完整消息历史记录，请查阅 API 文档，其中详细说明了消息检索端点。
是否可以在不知道用户 ID 的情况下将对话分配给坐席？
您可以先列出账户用户（坐席端点）以获取 ID，然后使用分配端点。坐席列表包括姓名和电子邮件，便于识别。
另请阅读
- 如何使用 Papo API 管理白标经销商客户
- 如何使用 Papo API 管理联系人的自定义属性
免费测试 Papo API 和所有模块——首位用户免费，且无需信用卡。