UnifyPort 文档：API、Webhooks 和 SDK 实用指南

UnifyPort 文档是开发者的入口，他们希望通过一个 REST API 在 Telegram、WhatsApp、LINE、X（原 Twitter）、Zalo 和 TikTok 之间发送和接收消息。无需学习六个特定于提供商的 SDK 和事件格式，您只需使用一个端点、一个标准化的 webhook 流以及一组共享概念：工作区、账户、运行时和 webhook 端点。

本指南将介绍文档的核心部分，解释各个部分如何组合在一起，并为您提供从第一次 API 调用到生产级 webhook 设置的清晰路径。

UnifyPort 文档涵盖的内容

官方文档围绕一个紧凑的开发者工作流组织：验证您的 API 密钥、连接账户、发送消息和接收标准事件。API 参考详细介绍了每个受支持频道的端点、负载和 webhook 事件。

您将遇到的关键部分包括：

• 入门：基础 URL、身份验证和第一个 API 调用
• 工作区：API 密钥的隔离边界
• 账户：每个频道的虚拟设备及其授权流程
• 运行时：每个账户背后的实时连接过程
• Webhook：持久的入站事件传递和签名验证
• SDK：Node.js、PHP、Go 和 Python 的官方客户端

如果您正在评估这是否适合您的技术栈，UnifyPort 功能概述 更详细地解释了标准事件层、webhook 控制平面、重试和速率限制。

基础 URL 和身份验证

UnifyPort 文档：API 参考、Webhooks 与 SDK - 基础 URL 和身份验证。

每个 API 请求都以基础 URL 开头：

https://api.unifyport.ai

所有 /v1 端点都使用 X-Api-Key 请求头进行身份验证。该密钥解析到恰好一个工作区，并授予对其的完全访问权限。您无需在请求正文中传递单独的工作区 ID。

验证密钥的快速方法是调用工作区端点：

curl https://api.unifyport.ai/v1/workspace \
  -H "X-Api-Key: <YOUR_API_KEY>"

请求 ID 和错误处理

JSON 成功和错误响应带有顶级 request_id。对于没有响应正文的请求，例如成功的 204 删除，该 ID 通过 X-Request-Id 响应头公开。报告问题时请引用该值。

您也可以发送自己的 X-Request-Id 请求头。它会在 JSON 响应中作为 client_request_id 回显，这有助于客户端对账。

文档中的核心概念

UnifyPort 文档：API 参考、Webhooks 与 SDK - 文档中的核心概念。

工作区

工作区是您的隔离边界。一个 API 密钥映射到一个工作区，您发送的每个账户、webhook 端点和消息都位于该工作区内。这使生产、暂存和客户端环境保持分离，而无需在代码中添加额外的路由逻辑。

账户

一个频道登录等于一个虚拟设备，称为账户。您通过 API 创建账户，使用提供商支持的流程（QR 码、登录码或会话导入）进行授权，然后通过它发送和接收消息。

运行时

运行时是每个账户背后的实时连接过程。它在授权成功后自动启动，其状态以 runtime_status 形式公开。账户生命周期文档描述了完整的状态机，包括连接中、已连接、已断开和错误状态。

Webhook

UnifyPort 没有 REST 消息历史读取 API，也没有保证的重放。您的 webhook 是入站流量的持久记录。首先注册一个 webhook 端点，并在到达时存储您需要的内容。

WhatsApp 在引导或重新连接后可能会发出有限的尽力而为的 HistorySync 事件，但这些不是完整的存档。请将您自己的 webhook 存储视为消息历史的唯一真实来源。

通过统一 API 发送消息

UnifyPort 文档：API 参考、Webhooks 与 SDK - 通过统一 API 发送消息。

发送消息使用单个端点，无论目标频道如何：

POST /v1/messages

同一端点处理文本、图像、文件和操作通知。您定位的账户决定了频道，因此您的应用程序代码不需要为出站传递提供特定于提供商的分支。

典型的发送流程如下：

1. 为您要使用的频道创建一个账户
2. 使用提供商的流程授权账户
3. 等待运行时达到已连接状态
4. 发送带有账户 ID 和消息负载的 POST /v1/messages 请求
5. 监控响应以及传递到您的 webhook 的任何状态事件

接收标准事件

入站消息、状态更新和账户事件都以标准事件的形式到达您的 webhook。UnifyPort 将每个提供商消息转换为一致的 JSON 形状，因此您的后端在所有频道中消费单一事件格式。

webhook 端点通过 API 进行管理。文档涵盖：

• 创建和激活端点
• 在轮换基础设施时停用端点
• 使用 HMAC-SHA256 进行签名验证
• 订阅管理
• 重试行为和失败跟踪

Webhook 端点生命周期

Python SDK 公开了诸如 deactivate_webhook_endpoint 之类的操作，它映射到：

POST /v1/webhook-endpoints/{endpoint_id}/deactivate

此操作不可重试且非破坏性，这意味着它只更改端点的活动状态，而不是永久删除它。endpoint_id 是必需的路径参数，并且支持可选的 X-Request-Id 头用于客户端跟踪。

Webhook 操作的身份验证与 API 的其余部分相同：X-Api-Key 来自客户端配置，而不是来自操作输入。

官方 SDK

UnifyPort 为四种语言提供官方 SDK：

• Node.js
• PHP
• Go
• Python

SDK 包装了 REST API，并为每个操作公开了显式方法。例如，Python SDK 提供了 deactivate_webhook_endpoint 作为相应 HTTP 操作的直接方法。这使您的集成保持类型化和可发现性，而无需手动构造 HTTP 请求。

SDK 遵循相同的身份验证模型：API 密钥在客户端上配置一次，单个操作不接受它作为参数。

推荐的开发者工作流

文档围绕一个足够简短的工作流设计：

1. 连接账户：将 Telegram 账户、WhatsApp 实例和其他提供商账户附加到同一工作区
2. 发送消息：使用统一的 /v1/messages 端点发送文本、图像、文件和操作通知
3. 接收事件：将入站消息和账户状态更改作为标准事件路由回您的 webhook

在基于 UnifyPort 构建之前，了解您正在统一的即时通讯格局会有所帮助。即时通讯概述 解释了 IM 平台的工作原理，以及为什么统一 API 策略可以减少集成开销。

Webhook 可靠性和生产默认值

UnifyPort 将自己定位为生产基础设施，而不是简单的频道聚合器。文档在几个方面反映了这一点：

• 重试队列：webhook 传递以可配置的行为进行重试
• 签名验证：HMAC-SHA256 签名让您验证事件来自 UnifyPort
• 自适应速率限制：内置速率限制减少了提供商动荡的影响
• 故障隔离：一个频道的问题不会导致整个管道中断

当您构建依赖可靠的多频道消息传递的通知系统、AI 代理、CRM 或运营工具时，这些默认值很重要。

从哪里开始

如果您是 UnifyPort 的新手，请按以下顺序操作：

1. 阅读入门部分并验证您的 API 密钥
2. 在发送任何消息之前注册一个 webhook 端点
3. 创建并授权您的第一个账户
4. 通过 /v1/messages 发送测试消息
5. 确认标准事件到达您的 webhook
6. 添加签名验证和重试处理
7. 转向适合您语言的 SDK，并将集成构建到您的应用程序中

有关特定于频道的上下文，LINE 功能指南 涵盖了 LINE 平台提供的内容，以及统一 API 如何简化该频道的集成。

相关阅读

• 排舞：步骤、歌曲和风格初学者指南 - 了解什么是排舞、它的历史、流行的舞蹈如 Electric Slide 和 Macarena、基本步骤、墙数，以及如何今天开始跳舞。

来源和进一步阅读

• API 参考 — UnifyPort - 用于通过一个统一 API 在 WhatsApp、Telegram、LINE、TikTok、Zalo 和 X 之间发送和接收消息的端点、负载和 webhook 事件。
• UnifyPort — 一个 API。每个频道。 - 通过一个 API 连接 WhatsApp、Telegram、LINE、TikTok、Zalo 和 X，用于消息和事件，无需为每个平台重建集成。
• UnifyPort-SDK-Python/docs/zh-CN/api-reference/deactivate-webhook-endpoint.md at main · Unify-Port/UnifyPort-SDK-Python - UnifyPort-SDK-Python。通过在 GitHub 上创建账户为 Unify-Port/UnifyPort-SDK-Python 开发做出贡献。

常见问题解答

UnifyPort API 的基础 URL 是什么？

基础 URL 是 https://api.unifyport.ai。所有 /v1 端点都相对于此基础，并使用 X-Api-Key 头进行身份验证。

UnifyPort 是否有用于读取消息历史的 REST API？

没有。UnifyPort 不提供 REST 消息历史读取 API，也不保证重放。您应该首先注册一个 webhook 端点，并将入站事件存储在您自己的系统中。WhatsApp 可能会发出有限的尽力而为的 HistorySync 事件，但它们不是完整的存档。

官方支持哪些 SDK？

官方 SDK 可用于 Node.js、PHP、Go 和 Python。每个 SDK 都包装了 REST API，并为可用操作公开了显式方法。

身份验证如何工作？

每个请求都使用 X-Api-Key 头进行身份验证。该密钥解析到恰好一个工作区，并授予对其的完全访问权限。请求正文中不需要单独的工作区 ID。

账户和运行时之间有什么区别？

账户是表示为虚拟设备的一个频道登录。运行时是该账户背后的实时连接过程。它在授权后自动启动，并将其状态公开为 runtime_status。

Webhook 签名如何工作？

UnifyPort 使用 HMAC-SHA256 签名对 webhook 事件进行签名。您可以在您的端点上验证这些签名，以确认事件来自 UnifyPort 并且未被篡改。

如果 webhook 传递失败会发生什么？

UnifyPort 包括一个具有可配置重试行为的重试队列。webhook 控制平面允许您管理签名、订阅、重试行为和失败跟踪，以便回调从第一天起就可观察。

结论

UnifyPort 文档围绕一组直接映射到实际集成工作的小概念构建：用于隔离的工作区、用于频道连接的账户、用于实时状态的运行时，以及用于持久入站事件的 webhook。一旦您理解了这四个部分，API 的其余部分就水到渠成了。

实现工作集成的最快路径是验证您的 API 密钥、注册 webhook 端点、授权账户，并通过 /v1/messages 发送您的第一条消息。从那里，官方 SDK 和标准事件层让您可以在 Telegram、WhatsApp、LINE、X、Zalo 和 TikTok 之间扩展，而无需为每个平台重建集成。