--- title: "核心概念" description: "平台中所有内容的概览——各个对象的作用、其在控制台中的位置，以及涉及它的 API。" --- ThunderPhone 是一个用于构建、运行和改进 AI 语音智能体的完整平台。本页是您的概览地图：您将遇到的每个概念各有一个简短章节，并说明其对应的控制台界面和底层 API。先快速浏览一遍，之后遇到需要进一步理解的术语时，随时回来查阅。 控制台侧边栏与此结构一致： [智能体](#agents)、[语音](#voices)、[电话号码](#phone-numbers)、 [网页小组件](#web-widgets)、[通话](#calls)、 [客户门户](#client-portals)、[知识库](#knowledge-bases)。 [实时监控](#live-monitoring)和外呼 [活动](#campaigns)。 您的智能体可使用的[应用、API、MCP 服务器和 VoIP 提供商](#connections)。 [模拟](#simulations)、[验证集](#validation-sets)、 [实验](#experiments)、 [问题](#issues)、[报告](#reports)、 [可观测性](#observability)。 [团队和角色](#team-and-roles)、[API 密钥](#organizations)、 [提醒](#alerts)、[计费](#billing)。 用于您自有代码的 [Webhook](#webhooks) 和[函数工具](#function-tools)。 --- ## 组织 **组织**是租户单元。其他所有资源——智能体、电话号码、通话和密钥——都只属于一个组织。您的账户可以属于多个组织；每个组织都有自己的余额、密钥和成员列表。 您在 **组织 → 密钥** 下创建的 `sk_live_` API 密钥会绑定到一个组织。正是这种绑定让 REST API 如此扁平：您无需在 URL 路径中加入组织 ID，因为您的密钥已可识别该组织。 **在控制台中可见的内容：组织切换器**（侧边栏底部）以及 **组织**设置——包含我的账户、常规、密钥、提醒、 计费设置和计费历史记录等标签页。请参阅 [组织设置参考](/zh/guides/organization-settings)。 **在 API 中：** [`/v1/orgs`](/api-reference/organizations)、 [`/v1/developer/api-keys`](/api-reference/developer-api-keys)。 --- ## 智能体 **智能体**是运行通话的 AI 配置。它包含： - 用于规定智能体说什么以及如何行为的**提示词**—— 包括转接、按键和挂断等通话操作；这些操作是普通提示词行，而非独立配置。 - **引擎层级**（`spark`、`bolt`、`storm-*`）：Spark 针对成本优化， Bolt 针对速度优化，Storm 针对复杂提示词的智能性优化。 - **语音**、**主要语言**以及可选的**附加语言**——当来电者切换语言时， 智能体会自动切换。请参阅[支持的语言](/zh/guides/supported-languages)。 - 已附加的能力：[已连接应用](#connections)、 [API 连接](#connections)、[知识库](#knowledge-bases)、 [MCP 服务器](#connections)和内联 [函数工具](#function-tools)。 - 行为设置：说话顺序、确认模式、背景音轨、等待超时。 您在构建器中进行的编辑会**自动保存为草稿**；只有点击 **部署** 后才会生效。每次部署都会在构建器的 **历史记录**标签页中创建快照，因此您可以查看并恢复任意先前版本。 **在控制台中：** **语音智能体** → 智能体构建器 (`/dashboard/agents`)。请参阅 [构建您的第一个语音智能体](/zh/guides/build-an-agent)。 **在 API 中：** [`/v1/agents`](/api-reference/agents)——CRUD、 复制、转接、版本历史记录和提示词辅助工具。 --- ## 语音 **语音库**包含智能体可使用的语音、可播放的示例、兼容语言、性别和口音分组，以及任何高级语音/语言附加费。您可以使用付费试听功能，在选择前合成您自己的 1–500 个字符短语。 符合条件的组织还可以根据简短的 WAV 或 MP3 样本创建**定制语音**。定制语音设有配额和异步创建状态；准备就绪后，它们会显示在与语音库相同的智能体选择器中。 **在控制台中：** **语音**（`/dashboard/voices`）。请参阅 [语音库和定制语音](/zh/guides/voice-library)。 **在 API 中：** [`/v1/voices`](/api-reference/voices)、 [语音样本](/api-reference/voice-samples)和 [定制语音](/api-reference/custom-voices)。 --- ## 电话号码 **电话号码**属于某个组织，并将呼入电话路由至智能体（也可用于外呼）。有两种来源： - **ThunderPhone 号码**——从 ThunderPhone 号码池配置的真实美国号码，数秒内即可启用，{/* rate:phone */}每月 $1，另加每分钟 1¢{/* /rate */} 附加费。它们初始仅支持呼入。组织管理员可从“电话号码”页面申请 呼出功能；ThunderPhone 会人工审核每项 申请，获批的号码即可拨打电话和运行营销活动。 默认情况下，一个组织最多可持有 25 个号码。 - **VoIP 号码**——通过 [VoIP 连接](#connections)从您自己的服务提供商引入。Twilio 和 Telnyx 可通过 API 密钥直接连接（Telnyx 还提供引导式新账户设置）； SignalWire、Vonage、Plivo 及任何其他 SIP 中继线路可通过 SIP 设置连接，这是一项手动 SIP 配置。导入并验证后，VoIP 号码支持呼入和呼出。 每个号码行都允许您设置路由模式、选择呼入智能体， 并为号码添加标签。 **在控制台中：** **电话号码**（`/dashboard/phone-numbers`）。 请参阅[获取电话号码](/zh/guides/get-a-phone-number)。 **在 API 中：** [`/v1/phone-numbers`](/api-reference/phone-numbers)、 [`/v1/voip-connections`](/api-reference/voip-connections)、 [`/v1/phone-number-labels`](/api-reference/phone-number-labels)。 --- ## 通话 每次呼入、外呼、模拟和小组件会话 都会生成一条**通话日志**。通话包含完整的角色标记转录文本、 结构化轮次历史记录（包括工具调用）、录音、 计费总额，以及可选的 AI 评分和问题报告。 通话处于**进行中**状态时，您可以打开并**旁听**——您会 静默加入，通话中的任何人都听不到您。开始旁听后，您可以 **悄悄提示**：输入一条指令，直接在通话过程中发送给您的智能体； 来电者永远听不到该指令，智能体会实时遵循它。 **在控制台中：** 使用 **通话记录**（`/dashboard/call-history`）查看 存档和单次通话详情；使用 **实时** 查看进行中的通话。请参阅 [查看、旁听和指导您的通话](/zh/guides/review-calls)。 **在 API 中：** [`/v1/calls`](/api-reference/calls)——列出、转录文本、 历史记录、音频、评分、导出； [`/v1/issue-reports`](/api-reference/issue-reports)。 --- ## 客户门户 **客户门户**是面向外部客户的品牌化只读通话记录视图。组织管理员可以选择 显示哪些智能体的通话，添加获批准的查看者电子邮件地址， 上传徽标和强调色，并可选择验证自定义域名。门户查看者可以查看通话详情、 转录文本和可用录音，而无需获得控制台访问权限。 **在控制台中：** **客户门户**（`/dashboard/client-portals`）。请参阅 [客户门户](/zh/guides/client-portals)。 **在 API 中：** [`/v1/client-portals`](/api-reference/client-portals) 用于 管理员管理界面。 --- ## 网页小组件 **网页小组件**让您的网站访客能够通过麦克风与智能体对话 ——无需电话号码。它使用**可发布密钥**（`pk_live_...`）进行身份验证，浏览器只能从 您允许的域名使用该密钥，因此可安全地用于客户端代码。域名列表 并非身份验证机制，且页面可发送的会话设置默认处于关闭状态，直到您在该密钥上允许它们。 密钥以以下两种模式之一运行：`agent`（静态绑定到一个智能体）或 `webhook`（您的服务器为每位访客选择配置——请参阅[按通话动态配置](/zh/guides/dynamic-call-config)）。小组件会话使用与电话通话相同的通话基础设施。 **在控制台中：** **网页小组件**（`/dashboard/web-widgets`）——创建小组件、设置模式和智能体、管理允许的域名，并复制嵌入代码片段。请参阅 [创建网页小组件](/zh/guides/embed-a-web-widget-dashboard)。 **在 API 中：** [`/v1/publishable-key`](/api-reference/publishable-keys)、 [`/v1/mic-session`](/api-reference/mic-sessions)以及 [小组件 SDK 文档](/zh/widget/overview)。 --- ## 知识库 **知识库**是一组可供您的智能体在通话过程中搜索的文档，用于为其回答提供依据——上传文件、粘贴文本或通过 URL 导入网页，然后在构建器中将知识库关联到智能体。当对话需要时，智能体会通过内置搜索工具查询知识库。 **在控制台中：** 文档库位于 **知识库**（`/dashboard/knowledge`）；在构建器的 **知识库** 部分将知识库关联到智能体。请参阅 [为您的智能体添加知识库](/zh/guides/knowledge-base)。 --- ## 连接 连接让智能体能够访问外部世界。共有四种类型，位于同一个侧边栏分组中： - **应用**（`/dashboard/app-connections`）——连接 Slack、HubSpot、Salesforce、Google Calendar、Google Sheets 和 Cal.com 的 OAuth。连接一次后，即可将按操作划分的工具（发送 Slack 消息、更新或创建 HubSpot 联系人、预约 Cal.com 时段……）切换到任意智能体。请参阅[连接应用](/zh/guides/connect-apps)。 - **API**（`/dashboard/api-connections`）——将任意 HTTP API 转换为智能体操作。粘贴 cURL 命令后，AI 向导会起草工具定义；您也可以手动构建。**测试请求**按钮会在您发布前发起沙盒调用。请参阅 [API 连接](/zh/guides/api-connections)——这是 [`/v1/integrations`](/api-reference/integrations) 的控制台界面。 - **MCP**（`/dashboard/mcp-connections`）——通过 URL 添加模型上下文协议服务器，并让智能体使用其公开的工具。请参阅[添加 MCP 服务器](/zh/guides/mcp-servers)。 - **VoIP**（`/dashboard/voip-connections`）——用于 [使用您自己的电话号码](#phone-numbers)的提供商凭据。请参阅 [连接 VoIP 提供商](/zh/guides/voip-providers)。 ThunderPhone 还提供自己的 MCP 端点，因此外部 MCP 客户端可以列出智能体、查看通话和转录文本，以及发起通话。请参阅 [将 ThunderPhone 用作 MCP 服务器](/zh/guides/thunderphone-mcp-server)。 **在 API 中：** [`/v1/integrations`](/api-reference/integrations)、 [`/v1/mcp-servers`](/api-reference/mcp-servers)和 [`/v1/voip-connections`](/api-reference/voip-connections)；另请参阅 [构建工具集成](/zh/guides/build-tool-integration)。 --- ## 活动 **活动**可大规模发起外呼：上传联系人 CSV，选择智能体和主叫号码，并设置呼叫时间窗口（日期和小时，支持时区）、并发数以及重试策略（最大尝试次数，以及哪些结果——未接听、语音信箱、失败——需要重试）。活动会依次处理列表，并在通话记录中记录每一通电话。 **在控制台中：** **活动**（`/dashboard/campaigns`）。请参阅 [运行外呼活动](/zh/guides/outbound-campaigns)。 **对于一次性以编程方式发起的通话：** 使用 [外呼 API](/zh/guides/place-outbound-calls)。 ## 实时监控 **实时**显示整个组织中正在进行的每一通电话，并允许您打开其中任意一通，以便实时[旁听和耳语](#calls)。这是监督界面：您可以观察新提示词迎来第一批真实流量，或关注正在运行的活动。 **在控制台中：** **实时**（`/dashboard/live`）。参见[观看和监督实时通话](/zh/guides/monitor-live-calls)。 --- ## 模拟 **模拟**是由 AI 呼叫方与您的智能体进行的一次真实对话——使用相同的电话路径、真实的转录文本和真实的评分——因此您可以在发布前（以及发布后）进行测试。您可以将其指向某个智能体或电话号码，自行编写呼叫方场景，或根据智能体的提示词**使用 AI 生成场景**（如您提出要求，还会包含边缘情况），并实时观看通话。 场景归入**套件**，套件可固定最低通过率，并能在 CI 中作为发布门槛；系统会按场景报告相对于已接受基线的回归问题。 **在控制台中：** **模拟**（`/dashboard/simulations`），以及智能体构建器中的 **模拟** 按钮。参见[模拟一次通话](/zh/guides/simulate-a-call)。 **在 API 中：** [`/v1/test-calls`](/api-reference/test-calls) 和套件运行器——参见[端到端测试智能体](/zh/guides/test-agents)。 --- ## 验证集 **验证集**将真实通话中的时刻转化为可重复执行的单轮回归检查。每个示例都会固定对话上下文、相关的呼叫方音频、原始响应和预期行为。重放会针对当前智能体草稿运行，无需再次拨打电话；部署对话框可以显示最新运行结果是否仍与该草稿一致。 **在控制台中：** 用于组织数据集的 **验证集**（`/dashboard/validation`），以及用于运行的智能体构建器 **验证** 选项卡。参见[验证集](/zh/guides/validation-sets)。 **在 API 中：** [`/v1/validation-sets`](/api-reference/validation-sets)，以及同一参考页面中的智能体／示例重放端点。 --- ## 实验 **实验**可在真实流量上对智能体配置进行 A/B 测试：定义变体（不同的提示词、引擎或设置），在它们之间分配流量，并按变体比较结果。请使用它，而不是在 webhook 中手动实现分桶逻辑。 **在控制台中：** **实验**（`/dashboard/experiments`）以及智能体构建器中的 **A/B** 选项卡。参见[实验（A/B 测试）](/zh/guides/experiments-ab-testing)。 --- ## 问题 **问题**是针对特定通话标记的故障——由人工审核员提交或通过 AI 评分检测。问题包含严重程度、来源和状态，而“问题”页面是分诊队列：您可以筛选、检查存在问题的通话，并跟踪修复进度。 **在控制台中：** **问题**（`/dashboard/issues`），以及通话记录中的按通话标记功能。参见[问题分诊](/zh/guides/issues)。 **在 API 中：** [`/v1/issue-reports`](/api-reference/issue-reports)。 --- ## 报告 **报告**会针对您的通话数据回答自然语言问题（“上周呼叫方要求转接人工的前三个原因是什么？”），并生成由 AI 撰写的分析，范围限定为您选择的智能体和日期范围。 **在控制台中：** **报告**（`/dashboard/reports`）。参见[报告](/zh/guides/reports)。 --- ## 可观测性 **可观测性**是指标界面：您可以按智能体和时间窗口筛选通话量、结果和随时间变化的质量指标，并导出数据以供下游分析。 **在控制台中：** **可观测性**（`/dashboard/observability`）。参见[可观测性](/zh/guides/observability)。 --- ## 警报 **警报规则**会在一个时间窗口内监测指标（成功率、失败率、平均得分、通话量、套件回归），并在其越过您设定的阈值时触发。通知将发送至电子邮件和 Slack，并向您的[webhook 端点](/zh/webhooks/endpoints)触发 `alert.triggered` 事件。 **在控制台中：** **组织 → 警报**。参见[警报](/zh/guides/alerts)。 --- ## Webhook 当通话期间或通话结束后发生事件时，ThunderPhone 会向您的服务器发送 **HTTP POST Webhook**。支持两种投递模式： - **Webhook 端点**（推荐）：在 [`/v1/developer/webhook-endpoints`](/zh/webhooks/endpoints) 中管理多个 URL， 并为每个端点设置独立密钥和事件订阅。 - **旧版单 URL Webhook**：每个组织一个 URL。在 [`/v1/webhook`](/api-reference/organizations#legacy-single-url-webhook) 或 **组织 → 常规** 中管理。保留此功能以实现向后兼容。 事件分为两类： - **阻塞事件**要求您的服务器返回用于塑造进行中通话的配置——即 [来电事件](/zh/webhooks/call-incoming) （`telephony.incoming` / `web.incoming`）。电话通话最长等待 13 秒，其中包括一次重试；组件会话最长等待 10 秒。 不提供备用智能体：如果没有可用配置，电话通话将被结束，组件会话将失败。 - **非阻塞事件**是即发即弃的通知，会采用指数退避进行重试——请参阅 [投递语义](/zh/webhooks/overview)。 每个请求都在 `X-ThunderPhone-Signature-V2` 中携带带时间戳的 HMAC-SHA256 签名， 以及仅针对请求正文的旧版 `X-ThunderPhone-Signature`。请参阅 [签名验证](/zh/webhooks/overview)。 --- ## 函数工具 **函数工具**是您的智能体可在对话过程中调用的 HTTP 端点。您向 ThunderPhone 提供 OpenAI 风格的函数架构和端点 URL；智能体决定何时调用它， ThunderPhone 会从其服务器发起已签名的 HTTP 请求，并将结果返回给智能体。 智能体还提供**内置通话功能**——转接通话、发送按键（DTMF）输入、结束通话、 保持等待——您只需通过普通提示词行启用这些功能，无需定义工具。 **在控制台中：** 构建器的 **API 连接**区域（请参阅 [连接](#connections)）。 **在 API 中：** [`/v1/integrations`](/api-reference/integrations) 和 [函数工具规范](/zh/tools/overview)。 --- ## 团队和角色 每个组织都有成员列表，并提供两种角色：**成员**负责构建和运营智能体； **管理员**还可管理团队和账单。通过电子邮件邀请成员——邀请将在 7 天后过期， 且可以撤销；成员行中的 ⋯ 菜单可用于更改角色或移除成员。可为整个组织配置 单点登录——请参阅 [SSO](/zh/guides/sso)。 **在控制台中：** **组织 → 常规**。请参阅 [邀请您的团队](/zh/guides/invite-your-team)。 **在 API 中：** [`/v1/members`](/api-reference/members)， [`/v1/invites`](/api-reference/invites)。 --- ## 账单 ThunderPhone 采用**预付费**模式。每个组织都有 USD 余额；通话会按智能体的 每分钟费率扣除余额（引擎层级加附加费——当您更改设置时，构建器会实时显示总费率， 并且[所选附加语言](/zh/guides/supported-languages)会增加 {/* rate:language */}3¢/分钟{/* /rate */}）。 当余额降至零时，呼入通话将被拒绝，呼出通话将返回 `402 Payment Required`。 您可以手动充值，或启用**自动充值**并设置余额阈值、充值金额以及可选的每月支出上限—— 确保通话不会在句子说到一半时中断。 **在控制台中：** **组织 → 账单设置**和 **账单历史记录**。请参阅 [充值并开启自动充值](/zh/guides/billing-and-topups)，以及 [完整定价参考](/zh/guides/pricing)。 **在 API 中：** [`/v1/billing`](/api-reference/billing)。 --- ## 应用内智能副驾 控制台内置**智能副驾**——向它询问“如何执行 X”，它会根据这些文档回答， 提供突出显示实际控件的逐步操作指南，并可重新播放任意引导式导览。这是查找本页面 提到的控件的最快方式。请参阅 [询问应用内智能副驾](/zh/guides/ask-the-copilot)。 --- ## 整合使用 五步向导：智能体 → 计费 → 号码 → 模拟 → 审核。 通过四个 REST 调用完成同一个首次通话。 创建智能体、充值、获取号码、模拟并审核通话。 OAuth 应用、自定义 API、MCP 服务器和 VoIP 提供商。 报告、可观测性、实验、问题和警报。 邀请和角色、API 密钥、安全性和 SSO。 API 示例：呼入、呼出、动态配置、工具、测试。 一次正确完成 HMAC 校验，随处复用。