AQUAVIA API

简介

一套 REST API 覆盖整个平台——发送短信、拨打电话、验证手机号、投递邮件或运行 AI 智能体，全部使用同一套身份验证、约定和 Webhook。

API 围绕可预测的、面向资源的 URL 设计。它接受 JSON 请求体，返回 JSON 响应，并使用标准的 HTTP 动词、状态码和身份验证方式。每个响应都包含请求 ID，方便支持团队准确追溯发生了什么。只要能发起 HTTPS 请求，就能使用 AtomMatrix——官方 SDK 只是对本文档所述同一批接口的轻量封装。

基础 URL 与版本管理

所有请求都通过 HTTPS 发送到同一个基础 URL，不支持明文 HTTP。

https://api.aquavia.ai/v1

API 的版本体现在路径中（/v1）。我们新增字段和接口时不会升级版本号，这类改动被视为向后兼容，你的集成应忽略未知字段。破坏性变更会以新版本发布，并提前通知、提供并行过渡期。建议固定使用 /v1，并阅读下文的约定，这样新增类改动就不会影响到你。

身份验证

每个请求都需要使用 API 密钥进行身份验证，密钥以 Bearer 令牌的形式放在 Authorization 请求头中。你可以在 AtomMatrix 控制台的“设置 → API 密钥”中创建和轮换密钥。

Authorization: Bearer sk_live_3f9c...your_key

密钥分为两种，通过前缀区分：

• sk_test_... —— 测试密钥。API 会完整处理请求，但不会真正发送到运营商或收件箱，也不会产生费用。请在开发和 CI 中使用。
• sk_live_... —— 正式密钥。真实的消息、真实的通话、真实的计费。

请妥善保管密钥。一个密钥即拥有对你账户的完整访问权限，切勿将其嵌入客户端代码、移动应用或公开仓库。如果密钥泄露，请在控制台中吊销——吊销会立即生效。请尽可能按环境和服务分别划分密钥。

没有有效密钥的请求会返回 401 Unauthorized。完整列表请参阅“错误与限制”。

快速上手

只需几步，就能从零完成第一次 API 调用。

• 在 AtomMatrix 控制台的“设置 → API 密钥”中获取测试密钥（sk_test_...）。
• 通过 HTTPS 向 https://api.aquavia.ai/v1 发送第一个请求，在 Authorization: Bearer 请求头中带上你的密钥，并使用 JSON 请求体。
• 查看 JSON 响应，并留意其中附带的请求 ID——支持团队可以凭它准确追溯发生了什么。
• 准备好处理真实流量后，切换为正式密钥（sk_live_...）。

通用约定

所有接口都遵循同一套约定，因此你学到的内容适用于消息、语音、验证、邮件和 AI 智能体。

• /v1 基础路径下可预测的、面向资源的 URL。
• JSON 请求体和 JSON 响应，使用标准 HTTP 动词和状态码。
• 每个响应都带有请求 ID，便于追溯和获得支持。
• 新增类改动不会发布新版本，请忽略你无法识别的字段。

短信

通过同一套 API 发送事务类和营销类短信。可编程短信涵盖时效性强的发送、大规模营销活动、支持回复和关键词的双向消息，以及按各市场规定选择的发送方 ID 和号码。

逐条消息的送达回执会报告状态、运营商级别的送达详情和明确的失败原因。退订处理和抑制名单帮助你保持合规。

语音通话

以编程方式拨打和接听电话。语音能力涵盖外呼通知、支持按键（DTMF）输入的 IVR 菜单、可应答、路由、排队并录音的呼入服务线路，以及支持 90 多种语言的文字转语音。

振铃、接听、结束等通话事件和录音可以接入你的工作流与分析，机器检测则能区分真人接听与语音信箱。

一次性验证码

使用一次性验证码验证手机号。验证码通过短信或语音发送，线路停滞时自动回退，确保验证码真正送达。

你可以控制有效期、重试次数以及单个号码请求验证码的频率，频率与欺诈控制则有助于防止验证流程被滥用。验证结果会同步到客户记录和你的工作流。

邮件

通过同一套 API 投递事务类和营销类邮件。邮件能力涵盖回执与提醒、营销活动与用户旅程、引导式域名认证（SPF、DKIM、DMARC）、发件人信誉，以及退信和投诉处理。

打开、点击和送达事件可供你据此采取行动，并回流到分析中。

AI 智能体

运行能够理解意图、检索知识、调用你的工具，并在需要判断时转交给真人的 AI 智能体。同一个智能体可以跨短信、聊天、语音和邮件传递上下文，支持 90 多种语言。

智能体与 API 的其他部分使用相同的身份验证、约定和 Webhook。

知识库与 RAG

让智能体的回答基于你认可的文档和实时业务数据，而不是凭空猜测。知识检索使回复来自你的帮助中心和政策，而不是泛泛的通用答案。

Webhook

Webhook 在平台的所有产品中工作方式一致。送达回执、通话事件、验证结果、邮件互动和智能体结果都会以事件的形式上报，让你的系统无需轮询就能保持同步。

错误与限制

API 使用标准的 HTTP 状态码，并返回 JSON 格式的错误响应。没有有效密钥的请求会返回 401 Unauthorized。

每个响应都包含请求 ID。联系支持团队时请附上它，以便他们准确追溯发生了什么。

SDK 与开发库

只要能发起 HTTPS 请求，就能使用 AtomMatrix。官方 SDK 只是对本文档所述同一批接口的轻量封装，因此无论采用哪种方式集成，本文档的内容都适用。