**借助 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](https://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 管理白标经销商客户](/hc/papo/articles/papo-api-white-label-reseller-client-management)
- 如何使用 Papo API 管理联系人的自定义属性

---

**[免费开始使用 →](https://chat.papo.global/app/auth/signup?papo_lp=home&utm_source=lp&utm_medium=landing&utm_campaign=home&utm_content=start-free&papo_lp_v=start-free)**

免费测试 Papo API 和所有模块——首位用户免费，且无需信用卡。