动作和工具

动作选项卡是您管理代理在对话之外可以做的所有事情的地方——代理在实时对话期间调用的工具、在通话开始之前运行的预取钩子,以及通话结束后触发的通话后动作。检索变量(代理从每次对话中提取的数据字段)位于同一选项卡中。

所有套餐

所有工具、动作和新的预取钩子在每个套餐(包括免费套餐)上都可用。

三个阶段

动作选项卡中的每个条目都属于三个生命周期阶段之一。添加工具下拉菜单将它们分组,以便清楚地了解每个事物何时触发:

阶段	何时	示例
预取	代理说"你好"之前	通过电话在您的 CRM 中查找来电者,拉取最新订单,从您的后端获取个性化问候
实时通话	在对话期间,由 AI 在合适的时机触发	将通话转接给人工、检查日历可用性、转接给另一个代理、查询外部 API 获取数据
通话后	通话结束后	发送摘要电子邮件、触发短信确认、将通话有效负载推送到您的 CRM

下拉菜单以预取位于顶部打开,因为其他每个阶段都已经有大量选项——新的预取条目最有可能是您正在寻找的东西。

预取

预取钩子让您的代理在通话开始时已经知道是谁在打电话。它们与通话设置并行运行,并在说出第一个字之前将响应注入代理的系统提示词中。

何时使用

通过电话号码识别返回的客户并按姓名问候他们
拉取来电者的未结订单、上次预约或会员级别
预加载取决于拨打哪条线的业务上下文
注入 CRM 备注,以便代理知道潜在客户的阶段和历史

它如何工作

平台解析来电者的电话(入站从 SIP,出站从拨号目标)。
每个活动预取动作并行触发,每个请求硬性超时 1.5 秒,总体预算 2 秒。
成功的响应作为命名块连接到代理的系统提示词中——代理在第一回合就读取它们。
失败是静默的——慢或损坏的端点永远不会阻塞问候。代理就在没有该块的情况下开始说话。

配置

字段	描述
名称	必需。内部标签和提示词中的块名称——保持简短且具有描述性(例如 `crm_lookup`、`vip_check`)。
API URL	必需。要获取的端点。支持 `{phone}`、`{direction}`、`{agent_id}`、`{user_id}`、`{call_id}` 占位符。
HTTP 方法	`GET` 是默认值且最适合。`POST` / `PUT` / `PATCH` / `DELETE` 也有效。
标头	可选。静态或模板化(占位符在此处也有效)。
查询参数	可选。新的预取动作预填充 `phone={phone}`。

可用变量

这些令牌在请求时替换到 URL、标头和查询/正文参数中:

变量	来源	示例值
`{phone}`	来电者的电话(E.164)——对于出站,目的号码	`+431234567890`
`{direction}`	`inbound` 或 `outbound`	`inbound`
`{agent_id}`	内部代理 ID	`65f1a2b3c4...`
`{user_id}`	工作区所有者 ID	`65e0b1c2d3...`
`{call_id}`	通话 ID(让您的后端稍后关联通话后有效负载)	`65f1f2c4d5...`

未知占位符按字面保留——错误的模板永远不会使通话崩溃。

提示词中包含什么

如果您在 https://crm.example.com/lookup?phone={phone} 的端点返回:

{ "name": "Sarah Johnson", "tier": "Gold", "open_orders": 1 }

代理的系统提示词会附加一个以动作命名的 XML 包装块:

<call_context>
  <block name="crm_lookup">
  { "name": "Sarah Johnson", "tier": "Gold", "open_orders": 1 }
  </block>
</call_context>

您不需要告诉代理如何使用它——LLM 自然会捕获上下文。可选地,在您的系统提示词中提及预取:"If <call_context> contains a customer name, greet them by name."

重要约束

仅限电话通话。 预取不为小部件(网络)通话运行——没有可模板化的电话号码。
响应正文上限 8 KB——超过的部分在注入前被截断。上限保护您的提示词令牌预算并限制恶意端点的爆炸半径。
无 condition 评估——预取在活动时始终触发。还没有要评估的转录。

提示

使用 GET 与电话键控的查找端点。保持响应小且结构化(具有 3-5 个字段的 JSON 对象)。代理不需要您完整的客户记录——只需要改变对话的部分。

实时通话工具

这些在对话期间运行。AI 根据其描述和当前对话决定何时调用每个工具。

可用工具

工具	用途	何时使用
呼叫转移	转接给人工接线员	客户要求真人、复杂问题
Google 日历	检查可用性并预约	客户想安排会议
Outlook 日历	相同,通过 Microsoft Outlook	客户想安排会议
API 工具 RAG	从外部 API 获取实时数据	需要实时信息(订单、库存、账户状态)
代理转接	转接给另一个 AI 语音代理	来电者需要不同的部门或专家
HubSpot CRM	在 HubSpot 中读取/写入联系人和交易	将通话记录到 HubSpot,查找潜在客户
MCP 服务器	暴露来自您注册的任何 MCP 服务器的工具	您运行 MCP 兼容的工具服务器,并希望代理在对话中使用其工具

呼叫转移

当满足特定条件时,将呼叫转接给人工。

设置	描述	示例
名称	必需。人员或部门名称	`"Sales Manager"`
转接号码	默认转接电话号码	`"+49 123 456 789"`
触发条件	代理何时应该转接	`"Customer asks for manager or issue cannot be resolved"`
条件路由号码	用于路由的条件到号码映射	`{"billing": "+49 111 222", "technical": "+49 333 444"}`

工作原理:

在对话期间,AI 评估触发条件。
如果设置了条件路由号码,匹配的条件确定要呼叫哪个号码。
否则,使用转接号码。
代理告知来电者有关转接的信息。
通话被转接——如果无人接听,它返回到代理。

提示

您可以为不同部门添加多个呼叫转移工具——一个用于"销售",另一个用于"技术支持",具有不同的条件和号码。

Google 日历

连接您的 Google 日历,以便代理可以在通话期间检查可用性并预约。

设置:

首先转到集成 → 日历并连接您的 Google 账户。
在代理的动作选项卡中添加 Google 日历工具。
选择要使用的日历。
配置您的可用性设置。

设置	描述	默认值
日历	必需。要使用的日历	您的主要日历
时区	预约的时区(IANA 格式)	自动检测
工作开始时间	工作时间的开始	上午 9:00
工作结束时间	工作时间的结束	下午 6:00
时段时长	预约长度(分钟)	30
工作日	一周中的可用日	周一至周五
预约之间的缓冲	预约之间的缓冲(0–60 分钟)	0

支持的时段时长:15、30、45、60、75、90、105、120 分钟。

提示

准确设置您的工作时间和日期——代理只会提供在您配置的可用性范围内的时间段。

Outlook 日历

连接您的 Outlook 日历以在通话期间安排预约。工作方式与 Google 日历相同。

设置:

首先转到集成 → 日历并连接您的 Outlook 账户。
在代理的动作选项卡中添加 Outlook 日历工具。
选择要使用的日历。
配置您的可用性设置。

设置与 Google 日历相同(时区、工作时间、时段时长、工作日、缓冲)。

代理转接

将通话转接给您账户上的另一个 AI 语音代理。当您有针对不同部门的专门代理时很有用。

设置	描述
目标代理	必需。选择要转接的代理
触发条件	何时转接(例如,"来电者询问技术支持")

示例: 前台代理在来电者询问价格时将其转接给销售代理,或在他们遇到技术问题时转接给支持代理。

HubSpot CRM

在通话期间读取和写入您的 HubSpot CRM。让代理记录交互、按电话查找联系人或推送交易更新,而无需您编写 API 调用脚本。

设置:

转到集成页面并连接您的 HubSpot 账户。
在代理的动作选项卡中添加 HubSpot CRM 工具。
选择代理应该被允许触及的管道和属性。

添加工具后,AI 可以通过电话将来电者匹配到 HubSpot 联系人,获取交易阶段并更新字段——全部从实时对话中完成。

MCP 服务器

暴露来自您已连接到 Hanc.AI 的任何 MCP 兼容服务器的工具。一个代理可以从多个 MCP 服务器拉取;一个 MCP 服务器可以服务多个代理。

设置:

在集成 → MCP 服务器下一次性连接您的 MCP 服务器。请参阅专门的 MCP 服务器页面了解完整的注册步骤。
将 MCP 服务器条目添加到此代理的动作选项卡——它在添加动作下拉菜单中归类于实时通话下。
切换此代理应该有权访问您注册的哪些连接。
添加简短的**"何时使用它"**指令,以便代理知道何时使用这些工具。

代理在每次通话开始时从每个启用的 MCP 服务器重新发现工具集,因此您在服务器端进行的更改会在下次通话时自动出现。工具以连接标签作为前缀重命名,以便来自不同服务器的同名工具不会冲突。

API 工具 RAG

连接到外部 API 以在通话期间获取实时信息——查找订单、检查库存、验证账户或访问任何通过 API 可用的数据。

设置	描述	示例
名称	必需。工具名称	`"Order Lookup"`
描述 / 何时使用	必需。何时查询 API	`"Customer asks about order status"`
API URL	必需。API 端点。可以包含将被来自正文参数模式(见下文)的值替换的 `{placeholder}` 令牌。	`"https://api.yourshop.com/orders/{order_id}"`
HTTP 方法	必需。HTTP 方法	`GET`、`POST`、`PUT`、`DELETE`、`PATCH`
加载消息	等待时代理说什么	`"Let me check that for you..."`
超时	最大等待时间(毫秒)	`5000`(默认)
标头	与每个请求一起发送的静态 HTTP 标头	`{"Authorization": "Bearer KEY"}`
查询参数	添加到每个请求的静态查询字符串参数	`{"apiVersion": "v2"}`
正文参数模式	必需。描述 AI 应从对话中提取并传递给工具的参数的 JSON Schema。请参阅编写正文参数模式。	JSON Schema 对象

提示

始终设置加载消息——API 调用期间的沉默对来电者来说感觉像是坏了。

备注

API 工具 RAG 上旧的"通话开始时运行"复选框已被专用的**预取**条目替换。当您希望在对话开始之前获取数据时使用预取;当代理应该在通话期间决定是否获取时使用 API 工具 RAG。

编写正文参数模式

尽管名称如此,正文参数模式不是原始请求正文。它是描述 AI 应从对话中提取并传递给您的工具的内容的 JSON Schema。根据 HTTP 方法和 URL 模板,这些值最终会出现在 URL、查询字符串或 JSON 正文中:

HTTP 方法	提取的值去哪里
URL 包含 `{name}`	匹配的值被替换到 URL 中
`GET`、`DELETE`	剩余的值作为 `?key=value` 附加到 URL
`POST`、`PUT`、`PATCH`	剩余的值作为 JSON 正文发送

最小结构

{
  "type": "object",
  "properties": {
    "param_name": {
      "type": "string",
      "description": "What this value is and how the AI should pick it"
    }
  },
  "required": ["param_name"]
}

根 type 始终为 "object"。properties 列出每个参数。required 标记 AI 必须始终提供哪些——如果客户尚未说出,AI 将在调用工具前询问。

字段参考

字段	目的
`type`	值的 JSON 类型:`"string"`、`"number"`、`"integer"`、`"boolean"`、`"array"`、`"object"`
`description`	最重要。告诉 AI 值的含义、使用什么格式以及何时提供它。尽可能添加示例。
`enum`	将值限制为固定列表之一。AI 会将自然语言映射到最近的选项(例如 `"the blue one"` → `"blue"`)。
`minimum`、`maximum`	数字边界。AI 将拒绝/钳制超出范围的值。
`default`	当 AI 不传递此字段时使用的值。不是必需的,但记录了隐式值。
`format`	验证提示,例如 `"email"`、`"date"`(YYYY-MM-DD)、`"uri"`。

示例

产品搜索(仅关键字):

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Product search keyword — e.g. \"phone\", \"laptop\", \"Apple\", \"Samsung\""
    }
  },
  "required": ["query"]
}

与 URL https://dummyjson.com/products/search?q={query}&limit=5 和 GET 一起使用:query 值进入 URL 占位符。正文中没有任何内容。

按 ID 查找订单:

{
  "type": "object",
  "properties": {
    "order_id": {
      "type": "string",
      "description": "Order ID the customer is asking about, usually 6 to 10 digits. Ask the customer if not provided."
    }
  },
  "required": ["order_id"]
}

与 URL https://api.example.com/orders/{order_id} 和 GET 一起使用。

具有多个必需字段的预订:

{
  "type": "object",
  "properties": {
    "product_id": {
      "type": "string",
      "description": "Product ID returned by a previous search_products call."
    },
    "quantity": {
      "type": "integer",
      "minimum": 1,
      "maximum": 10,
      "description": "How many items to reserve. Default 1."
    },
    "delivery_method": {
      "type": "string",
      "enum": ["pickup", "home_delivery", "locker"],
      "description": "How the customer wants to receive the item."
    },
    "customer_email": {
      "type": "string",
      "format": "email",
      "description": "Customer's email for order confirmation. Ask if not provided."
    }
  },
  "required": ["product_id", "delivery_method", "customer_email"]
}

与 POST https://api.example.com/reservations 一起使用:四个值进入 JSON 正文。AI 将在调用工具之前向客户询问缺失的 required 字段。

无参数的工具:

{
  "type": "object",
  "properties": {}
}

当端点完全静态(例如 GET /store/hours)且 AI 不需要传递任何内容时使用。

AI 语音代理的最佳实践

**保持模式平坦。**嵌套对象和数组可以工作,但 AI 在通过电话讲话时可能会滑动。最多优先选择 3–5 个顶级字段。
**始终为每个字段编写 description。**包括示例(e.g. "phone", "laptop")——示例比抽象定义更可靠地指导 AI。
**当您有固定的值列表时,使用 enum。**它消除了 AI 发明值或发送 "Electronics" 而不是 "electronics" 的风险。
**仅当工具没有它就无法工作时才将字段标记为 required。**其他一切都是可选的,当客户没有提到时,AI 将跳过它——没有尴尬的额外问题。
使用 snake_case 名称并精确匹配 URL 中的任何 {placeholder} 令牌。
在 description 中记录缺失值的行为——例如 "Omit if no budget limit"、"Default 5"。

通话后动作

通话后动作在通话结束并且分析链产生摘要、情感和提取的变量后触发。它们消费通话数据——它们不与客户交谈。

可用动作

动作	用途
发送电子邮件	向您的团队或客户发送结构化摘要电子邮件
发送短信	给来电者发送文字确认
发送 WhatsApp	WhatsApp 消息或模板(在 24 小时窗口内外均工作)
API 调用	将完整通话有效负载推送到外部 API(CRM、Webhook、您的数据仓库)

发送电子邮件

设置	描述
名称	必需。动作标识符
主题	必需。电子邮件主题行
消息正文	必需。电子邮件正文——可以包括检索变量
触发条件	何时发送(空 = 始终)
收件人	必需。始终接收电子邮件的电子邮件地址
条件收件人	条件到收件人的映射

在电子邮件中使用变量:

New lead from phone call:

Name: {{customer_name}}
Email: {{customer_email}}
Interested in: {{selected_plan}}
Notes: {{call_notes}}

发送短信

设置	描述
名称	必需。动作标识符
发送者名称	显示的发送者名称
消息	必需。短信内容(可以包括变量)
触发条件	何时发送
收件人	必需。始终接收短信的电话号码
条件收件人	条件到号码的映射

发送 WhatsApp

HANC 上的 WhatsApp 消息使用来自中央 Twilio Content 账户的预先批准的模板——您不会手动粘贴模板 SID。动作编辑器显示当前活动并批准的每个模板的下拉菜单,您选择一个。模板内的占位符({{1}}、{{2}},...)然后从您在编辑器中映射的通话变量或静态文本内联填充。

设置	描述
名称	必需。动作标识符
触发条件	何时发送
收件人	必需。始终接收消息的电话号码
条件收件人	条件到号码的映射
模板	必需。从中央 Twilio Content 账户同步的预先批准的 WhatsApp 模板的下拉选择器。每个条目显示模板名称、语言和正文预览,以便您知道选择哪一个。
模板变量	对于您选择的模板,编辑器列出每个占位符(`{{1}}`、`{{2}}`,...)并让您将其映射到通话变量(见下文)或静态字符串。

您可以映射到模板占位符的可用通话变量:

变量	描述
`{{call_from}}`	来电者的电话号码
`{{call_to}}`	被呼叫的号码
`{{call_summary}}`	AI 生成的通话摘要
`{{call_sentiment}}`	情感(积极/中性/消极)
`{{call_task_achieved}}`	通话任务是否完成
`{{call_transcription}}`	完整通话转录

为什么是选择器,而不是自由文本

WhatsApp 要求在 24 小时客户服务窗口之外由企业发起的每条消息使用预先批准的模板。HANC 从共享的 Twilio Content 账户同步批准的模板列表,因此下拉菜单始终准确显示现在可以发送的内容——您不能意外选择草稿、被拒绝的模板或不存在的 SID。要添加新模板,请联系支持;一旦获得 WhatsApp 的批准,它就会自动出现在下拉菜单中。

API 调用

通话后 API 调用动作是您进入堆栈其余部分的通用 Webhook。选择方法,设置 URL,我们将发送整个通话有效负载——您的端点接收一个描述发生情况的结构化 JSON 对象。

设置	描述
名称	必需。动作标识符
触发条件	何时触发(空 = 每次通话)。由 LLM 根据转录评估。
API URL	必需。API 端点 URL
HTTP 方法	必需。`GET`、`POST`、`PUT`、`DELETE`、`PATCH`
标头	可选请求标头
查询参数	可选查询字符串参数

您的端点接收什么

对于 POST / PUT / PATCH,您的端点在请求正文中获得一个 JSON 对象。您配置的正文参数与完整通话有效负载合并:

{
  "call_from": "+431234567890",
  "call_to":   "+439876543210",
  "direction": "inbound",
  "call_type": "phone",
  "call_status": "ended",
  "start_timestamp": 1730000000000,
  "end_timestamp":   1730000187000,
  "duration": 187000,
  "transcription": [
    { "speaker": "agent", "content": "Hello…", "timestamp": 1730000001000 },
    { "speaker": "user",  "content": "Hi…",    "timestamp": 1730000003000 }
  ],
  "call_summary": "Customer asked about pricing…",
  "task_achieved": true,
  "sentiment": { "sentiment": "positive", "explanation": "…" },
  "custom_analysis_data": {
    "name": "John",
    "email": "john@example.com"
  },
  "collected_data": { /* in-call form submissions */ },
  "transfer_history": [ /* if any agent transfer happened */ ],
  "recording_url": "https://…",
  "disconnection_reason": "user_hangup",
  "is_anonymous": false,
  "is_simulation": false,
  "created_at": 1730000000000,
  "updated_at": 1730000187000
}

对于 GET / DELETE,相同的字段被展平到查询字符串中——但像 transcription、sentiment 和 custom_analysis_data 这样的嵌套值被丢弃(URL 无法合理地携带结构化数据)。如果您需要转录,请使用 POST/PUT/PATCH。

每个请求还获得一个用于跟踪的 X-Correlation-Id 标头,并在 30 秒后超时。

预取 vs 通话后 API 调用

预取将 {phone} 等模板化到 URL/标头/查询/正文。在通话之前进入提示词返回。
通话后 API 调用在正文或查询中发送整个通话转储。无 URL 模板化——您的端点获得静态 URL + 动态正文。

检索变量

检索变量是 AI 自动从对话中提取的自定义数据字段。例如,代理可以捕获来电者的姓名、电子邮件、电话号码或您定义的任何其他信息。

默认变量

每个新代理都使用两个默认检索变量创建:

变量	类型	描述
电子邮件	电子邮件	来电者的电子邮件地址
电话	电话	来电者的电话号码

这些默认启用并显示在通话小部件表单中。您可以编辑或删除它们,并添加自己的自定义变量。

变量类型

类型	用例	示例
文本	姓名、地址、备注、自由格式输入	客户姓名、送货地址
数字	数量、预算、ID	订单数量、预算金额
电子邮件	带验证的电子邮件地址	客户电子邮件
电话	带验证的电话号码	客户电话号码
选择器	从预定义选项中选择	首选套餐(Basic/Pro/Enterprise)
复选框	是/否同意或确认	"我同意接收营销电子邮件"

配置变量

字段	描述	示例
变量名称	必需。变量标识符	`customer_email`
AI 指令	必需。AI 何时以及如何提取此值的指令	`"The customer's email address. Ask if not provided."`
示例格式	(可选) 预期格式的示例	`"john@example.com"`
选项(用于选择器)	(仅选择器) 允许选项的列表	`["Basic", "Pro", "Enterprise"]`
在表单中显示	是否在通话小部件表单中显示此字段	默认启用

在表单中显示

启用在表单中显示时,变量会在通话之前和期间在 Web 小部件中显示为可见的输入字段。这让来电者可以直接填写他们的信息,除了 AI 从对话中提取之外。

提示

AI 将在对话期间自然地询问缺失的信息。设置一个清晰的描述,如"客户的电子邮件地址,如果未提供请礼貌地询问",代理就会处理它。

添加工具和动作

导航到您的代理的动作选项卡。
点击添加工具。
从下拉菜单中选择正确的阶段——预取、实时通话或通话后。
配置设置。
保存——更改在下次通话时生效。

所有条目都一起列在动作表中。点击任何行进行编辑,或使用垃圾桶图标删除。

三个阶段​

预取​

何时使用​

它如何工作​

配置​

可用变量​

提示词中包含什么​

重要约束​

实时通话工具​

可用工具​

呼叫转移​

Google 日历​

Outlook 日历​

代理转接​

HubSpot CRM​

MCP 服务器​

API 工具 RAG​

编写正文参数模式​

最小结构​

字段参考​

示例​

AI 语音代理的最佳实践​

通话后动作​

可用动作​

发送电子邮件​

发送短信​

发送 WhatsApp​

API 调用​

您的端点接收什么​

检索变量​

默认变量​

变量类型​

配置变量​

在表单中显示​

添加工具和动作​

相关​

三个阶段

预取

何时使用

它如何工作

配置

可用变量

提示词中包含什么

重要约束

实时通话工具

可用工具

呼叫转移

Google 日历

Outlook 日历

代理转接

HubSpot CRM

MCP 服务器

API 工具 RAG

编写正文参数模式

最小结构

字段参考

示例

AI 语音代理的最佳实践

通话后动作

可用动作

发送电子邮件

发送短信

发送 WhatsApp

API 调用

您的端点接收什么

检索变量

默认变量

变量类型

配置变量

在表单中显示

添加工具和动作

相关