Open in
函數工具
為你的 AI 智能體提供函數工具,可在對話期間呼叫外部 API——擷取客戶資料、預約、更新記錄——並支援具類型的參數。
函數工具讓你的 AI 智能體可在通話期間調用外部 API。你可用它們查詢客戶資料、檢查可用時段、預約服務,或執行後端支援的任何操作。
運作方式
- 以綱要定義工具(工具可接受哪些參數)
- 提供
endpoint設定(ThunderPhone 在何處調用你的 API)——或不設定,以便透過組織 webhook 接收工具調用 - 通話期間,AI 會根據對話決定何時使用工具
- ThunderPhone 會連同工具參數調用你的端點
- 你的 API 回應會傳回 AI,以繼續對話
| 功能 | 執行位置 | 設定方式 |
|---|---|---|
| 內建工具 | ThunderPhone | 提示指示;部分工具亦需要設定智能體 |
| 應用程式連接 | ThunderPhone 及已連接的服務供應商 | 連接帳戶並附加已核准操作 |
| API 連接及函數工具 | 你的 HTTP API | 定義端點及綱要,或透過 webhook 接收函數調用 |
| MCP 伺服器 | 遠端 MCP 伺服器 | 新增伺服器、探索其工具,並將其附加至智能體 |
工具綱要
每個工具均遵循以下結構:
{
"type": "function",
"function": {
"name": "search_appointments",
"description": "Find available appointment slots for a given date",
"parameters": {
"type": "object",
"properties": {
"date": {
"type": "string",
"description": "Date in YYYY-MM-DD format"
},
"service": {
"type": "string",
"description": "Type of service (e.g., 'consultation', 'follow-up')"
}
},
"required": ["date"]
}
},
"endpoint": {
"url": "https://api.example.com/appointments/search",
"method": "POST",
"headers": {
"X-Api-Key": "your-api-key"
}
},
"timeout": 120
}工具設定
| 欄位 | 類型 | 必填 | 說明 |
|---|---|---|---|
timeout | 數字 | 否 | 最長執行時間(秒)(預設:20,上限:180;如使用 wait_mode: "hold",則為 600) |
wait_mode | 字串 | 否 | 工具執行期間來電者會聽到的內容:updates(預設),即簡短語音更新;或 hold,即等候音樂。請參閱長時間等候:等候模式及稍後回覆 |
call_start | 物件 | 否 | 亦可在每次電話通話開始時、問候語之前自動執行工具。請參閱在通話開始時執行工具 |
函數定義
| 欄位 | 類型 | 必填 | 說明 |
|---|---|---|---|
name | 字串 | 是 | 工具識別碼,在同一通通話的工具之中必須唯一。不同智能體可各自擁有名稱相同的工具 |
description | 字串 | 是 | 說明 AI 何時應使用此工具 |
parameters | 物件 | 是 | 工具引數的 JSON Schema |
端點設定
| 欄位 | 類型 | 必填 | 說明 |
|---|---|---|---|
url | 字串 | 是 | 你的 API 端點 URL |
method | 字串 | 否 | HTTP 方法(預設:POST) |
headers | 物件 | 否 | 要包括的自訂標頭 |
兩種調用路徑
你的伺服器會收到哪一種請求,取決於工具是否設有
endpoint:
設有 endpoint 的工具 | 未設 endpoint 的工具 | |
|---|---|---|
| 請求發送位置 | 直接發送至 endpoint.url | 你機構的舊版 webhook URL |
| 主體 | 所選請求格式(預設為純參數) | telephony.tool / web.tool 封裝 |
| 標頭 | 你的 endpoint.headers + X-ThunderPhone-Call-ID + X-ThunderPhone-Signature-V2 + X-ThunderPhone-Signature,以及電話通話時的通話號碼 | Content-Type + X-ThunderPhone-Signature-V2 + X-ThunderPhone-Signature |
| 簽名金鑰 | 機構 webhook 密鑰 | 機構 webhook 密鑰 |
兩種路徑均為 阻塞式——AI 會在句子中途等待結果。預設逾時時間為 20 秒;設定工具頂層的 timeout,即可容許較長的執行時間,最長可達平台上限 180 秒。處理程式應保持快速。如需等待真人或較慢的工作,請使用保留模式。你可混合使用:在所屬組織設有 webhook URL 的通話中,設有 endpoint 的工具會直接呼叫,其餘則回退至 webhook。
直接端點呼叫
當 AI 呼叫具有 endpoint 的工具時,ThunderPhone 會向你的 URL 傳送
請求:
請求標頭
POST /appointments/search HTTP/1.1
Host: api.example.com
Content-Type: application/json
X-ThunderPhone-Signature-V2: t=1767225600,v1=5f2c...
X-ThunderPhone-Signature: abc123...
X-ThunderPhone-Call-ID: 987654321
X-ThunderPhone-From-Number: +14155550199
X-ThunderPhone-To-Number: +14155550100
X-ThunderPhone-Call-Direction: inbound
X-Api-Key: your-api-key你在 endpoint.headers 設定的自訂標頭一律會原樣附上,
另加以下以 ThunderPhone 為命名空間的標頭:
X-ThunderPhone-Signature-V2—— 以你機構的 webhook 密鑰 作為金鑰,對方法、路徑、查詢及主體進行附有時間戳記的 HMAC-SHA256 簽署。 請驗證此簽署並拒絕超過 5 分鐘的請求;請參閱 驗證 webhook 簽署X-ThunderPhone-Signature—— 對請求主體原始位元組進行的舊版 HMAC-SHA256 簽署,使用相同金鑰,仍會傳送以支援現有驗證器X-ThunderPhone-Call-ID—— 目前通話 IDX-ThunderPhone-From-Number及X-ThunderPhone-To-Number—— 通話的 From 及 To E.164 號碼。其含義與telephony.complete中的from_number及to_number相同:對外撥通話而言,From 是你智能體的號碼,而 To 是被致電人士的號碼。來電顯示被隱藏或並非電話號碼時,將不會包含該號碼X-ThunderPhone-Call-Direction——inbound或outbound,讓你識別哪個號碼屬於客戶
通話號碼標頭只會在電話通話中傳送。網頁、小工具、即時及瀏覽器 Talk 測試均沒有電話號碼,因此不會包含這些標頭。來自智能體編輯器及 AI 模擬的測試通話會包含模擬來電者的號碼。簽署不涵蓋標頭:V2 會簽署時間戳記、方法、路徑、查詢及主體。如需對號碼進行簽署,請改為從主體讀取:retell 請求格式包含全部三項,而 vapi 則包含客戶的號碼。
除非你的 endpoint.headers 覆寫,否則會設定
Content-Type: application/json —— 自訂 Content-Type 會優先採用。
請求格式
每個 API 連線均設有 request_format 設定。當匯入的工具需要繼續呼叫為該平台建立的端點時,請選擇 vapi 或 retell。新增及現有連線預設為 standard。
對於 POST / PUT / PATCH,ThunderPhone 會以標準化方式序列化所選封裝格式(排序鍵、精簡分隔符)。兩個簽章均涵蓋這些完全相同的位元組。
Standard
standard 只會傳送工具參數,不設包裝格式。這是預設選項,並會逐位元組保留 ThunderPhone 原始請求主體:
{"date":"2025-01-02","service":"consultation"}Vapi
vapi 會以 Vapi 文件所述的格式,傳送 Vapi 的 tool-calls 伺服器訊息。
call.id 為 ThunderPhone 通話 ID。
在電話通話中,call.customer.number 是另一方的電話號碼,與
Vapi 的通話物件一致:來電通話中的來電者,或撥出通話中的被叫方。當該號碼被隱藏或並非
電話號碼時,則不會包含此欄位。工具呼叫的 id 對每次調用均為唯一,並會
重用以配對端點的結果。通話會同時出現在 toolCallList 及
toolWithToolCallList 中,而 function.arguments 則為 JSON 物件:
{
"message": {
"type": "tool-calls",
"timestamp": 1725000000123,
"call": { "id": "987654321" },
"toolCallList": [
{
"id": "call_00112233445566778899aabbccddeeff",
"type": "function",
"function": {
"name": "search_appointments",
"arguments": { "date": "2025-01-02", "service": "consultation" }
}
}
],
"toolWithToolCallList": [
{
"type": "function",
"function": { "name": "search_appointments" },
"toolCall": {
"id": "call_00112233445566778899aabbccddeeff",
"type": "function",
"function": {
"name": "search_appointments",
"arguments": { "date": "2025-01-02", "service": "consultation" }
}
}
}
]
}
}不會傳送僅限 Vapi 的欄位,例如 assistant、artifact 及完整的 call 物件。
請傳回包含相符工具呼叫 ID 的 Vapi 回應封裝:
{
"results": [
{
"toolCallId": "call_00112233445566778899aabbccddeeff",
"result": "{\"available_slots\":[\"9:00 AM\",\"2:00 PM\"]}"
}
]
}ThunderPhone 會向 AI 提供未封裝的 result 字串。為相容已經傳回 JSON 值的端點,亦接受 JSON 值。如以 error 取代 result,將作為工具錯誤傳回 AI。如端點傳回格式錯誤或不相符的 Vapi 封裝,ThunderPhone 會記錄警告,並改用其標準回應解析方式,而不會令通話失敗。
Retell
retell 會傳送 Retell 自訂函數文件所述的請求:
{
"name": "search_appointments",
"call": {
"call_id": "987654321",
"from_number": "+14155550199",
"to_number": "+14155550100",
"direction": "inbound"
},
"args": { "date": "2025-01-02", "service": "consultation" }
}在電話通話中,call 物件包含 call_id、from_number、
to_number 及 direction(inbound 或 outbound),這些是
Retell 的電話通話物件所使用的欄位名稱。它們與通話號碼標頭相符,
而且與標頭不同的是,兩種簽章均涵蓋這些欄位。已隱藏或並非電話號碼的
號碼將不會包括在內。在網頁、小工具、即時及瀏覽器 Talk 測試中,則只包含
call_id。ThunderPhone 不會包括
在派送時無法如實提供的 Retell 專用欄位,例如
agent_id、transcript、transcript_object、metadata 或
動態變數。Retell 接受任何回應內容;ThunderPhone 會使用標準回應處理機制直接傳遞。
對於 GET / DELETE,引數會以查詢參數傳送,而不論 request_format 為何,請求主體均為空。V2 簽章涵蓋實際傳送的查詢字串;舊版簽章則根據空位元組字串計算。請參閱驗證 webhook 簽章。
回應
以 JSON 回應工具結果:
{
"available_slots": ["9:00 AM", "2:00 PM", "4:30 PM"],
"timezone": "America/Los_Angeles"
}回應會經過格式化並提供予 AI,以繼續對話。非 JSON 回應會包裝為
{"data": "<text>"};逾時及連線失敗會以錯誤形式報告予 AI,
讓智能體可以致歉並繼續處理,而不會停滯。
Webhook 模式分派
沒有 endpoint 的工具,會以已簽署的 telephony.tool(電話通話)或 web.tool
(網頁通話)請求,分派至你機構的舊版 webhook URL。與工具執行後
傳送至 webhook 端點的稽核通知不同,此請求就是
執行本身 —— 你的 HTTP 回應即為工具結果。
{
"type": "telephony.tool",
"data": {
"call_id": 987654321,
"tool_name": "search_appointments",
"arguments": { "date": "2026-04-21" },
"from_number": "+14155550199",
"to_number": "+15551234567"
}
}web.tool 會帶有 origin_domain,而非 from_number /
to_number。請以 JSON 回傳工具結果——其回應規格與直接端點呼叫相同。此請求會以組織的 webhook 密鑰簽署,並包含兩個簽署標頭,與其他所有 webhook 一樣。
長時間等候:等候模式及稍後回覆
部分工具需要等待真人處理:例如經理批准折扣,或業主在 Slack 回答問題。請為這些
工具將 wait_mode 設為 "hold"。
wait_mode: "updates"(預設) | wait_mode: "hold" | |
|---|---|---|
| 來電者聽到的內容 | 工具啟動提示,約 12 秒後會有簡短的「仍在處理中」提示,其後約每 15 秒再提示一次 | 工具啟動提示,其後播放等候音樂,直至收到結果 |
timeout 最大值 | 180 秒 | 600 秒 |
| 待處理回覆 | 作為結果傳送至智能體 | 工具會保持開啟,直至你提交結果 |
在等候模式下,智能體會在工具啟動時說一句提示(可使用自己的措辭, 或使用智能體上設定的工具啟動提示),其後來電者會聽到等候音樂。 智能體讀出結果前,音樂會逐漸淡出。若工具在一兩秒內回覆,則不會播放 任何音樂。當智能體正在與電話選單或留言信箱互動時,會改用語音更新提示, 因為音樂可能會被視為回覆。這亦包括在等候期間才偵測到是選單或留言信箱的 通話:音樂會停止,並改為語音更新提示。無法播放音樂的通話亦會如此處理。
若來電者在等候期間說話,音樂會繼續播放,而智能體暫時不會回應。 智能體會聽取來電者所說的內容,並在提供結果時一併回覆。掛線會結束通話 及尚未完成的工具。
稍後回覆
你的端點本身仍必須在 180 秒內回應。若要讓來電者等候更長時間,請立即 回覆一個待處理結果:
{ "status": "pending", "request_id": "ask-4471" }request_id 可以是最多 200 個字元的任何字串,用於在你的一方識別此
請求。來電者會一直保持等候,直至你透過
POST /v1/calls/{call_id}/tool-results
提交結果。call_id 是工具請求中的 X-ThunderPhone-Call-ID 標頭。
curl -X POST https://api.thunderphone.com/v1/calls/987654321/tool-results \
-H "Authorization: Bearer sk_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"request_id": "ask-4471",
"result": { "answer": "Yes, book Tuesday at 10." }
}'智能體會將 result 視為工具的回覆,與你的端點直接傳回該結果的情況
相同。若在工具被呼叫起計的 timeout 前仍未收到結果,智能體會得知
未有回覆,並向來電者提供下一步選項,例如留言。
你可隨時提交結果,即使你的待處理回應尚未送達 ThunderPhone。一個 202
表示該通電話已接收結果:尚未完成的請求已接收該結果,或工具本身的請求
仍在傳送中,而其待處理回覆將會認領該結果。若結果從未被任何請求認領
(即你的端點其後就該 request_id 回覆了待處理以外的內容),該結果會被捨棄。
若連線設有回應轉換(即在智能體看到之前改寫你的端點回覆的程式碼),
轉換會套用至你的端點本身回覆,並在 ThunderPhone 檢查待處理回覆之前執行,
因此待處理回覆必須保留 status 及 request_id。你其後提交的結果不會
經過轉換:智能體會按你提交的內容接收該結果。
全雙工智能體不會播放等候音樂或提供更新提示,因此在其通話中,等候工具
的行為與 updates 工具相同:待處理回覆會作為工具結果傳送至智能體。
updates 模式工具的待處理回覆不會保持開啟:智能體會將其作為工具結果接收。
簽名驗證
直接工具呼叫會以與 webhook 相同的方式簽署,並使用你機構的 webhook 密鑰:
X-ThunderPhone-Signature-V2會簽署傳送時的時間戳記、方法、路徑及查詢字串,以及完整的請求主體位元組。若請求的時間戳記與你的時鐘相差超過 5 分鐘,請拒絕該請求。X-ThunderPhone-Signature(舊版)只會簽署請求主體位元組;對於GET/DELETE,則簽署空位元組字串。此標頭仍會照常傳送,內容不變。
SDK 輔助工具會驗證 V2 標頭,包括 5 分鐘時限:
import json
from fastapi import FastAPI, HTTPException, Request
from thunderphone import verify_signature
app = FastAPI()
@app.post("/appointments/search")
async def search_appointments(request: Request):
body = await request.body()
query = request.scope.get("query_string", b"").decode("latin-1")
path = request.url.path + (f"?{query}" if query else "")
if not verify_signature(
request.headers.get("X-ThunderPhone-Signature-V2"),
secret=WEBHOOK_SECRET,
method=request.method,
path=path,
body=body,
):
raise HTTPException(status_code=401)
data = json.loads(body)
date = data["date"]
# Look up availability
slots = await get_available_slots(date)
return {"available_slots": slots}import express from "express";
import { verifySignature } from "@thunderphone/sdk";
app.post('/appointments/search', express.raw({type: 'application/json'}), (req, res) => {
const ok = verifySignature({
header: req.header('X-ThunderPhone-Signature-V2'),
secret: WEBHOOK_SECRET,
method: req.method,
path: req.originalUrl,
body: req.body,
});
if (!ok) return res.status(401).send('Invalid signature');
const { date, service } = JSON.parse(req.body);
// Look up availability
const slots = getAvailableSlots(date, service);
res.json({ available_slots: slots });
});完整操作範例——包括已簽署字串、完整示例、不使用 SDK 的程式碼、GET / DELETE 情況,以及沒有密鑰時的注意事項——請參閱驗證 webhook 簽署。
範例:完整預約流程
以下是一組適用於完整預約系統的工具:
{
"tools": [
{
"type": "function",
"function": {
"name": "search_appointments",
"description": "Find available appointment slots",
"parameters": {
"type": "object",
"properties": {
"date": { "type": "string", "description": "YYYY-MM-DD" },
"service": { "type": "string" }
},
"required": ["date"]
}
},
"endpoint": {
"url": "https://api.example.com/appointments/search",
"method": "POST",
"headers": { "X-Api-Key": "key" }
}
},
{
"type": "function",
"function": {
"name": "book_appointment",
"description": "Book an appointment at a specific time",
"parameters": {
"type": "object",
"properties": {
"date": { "type": "string", "description": "YYYY-MM-DD" },
"time": { "type": "string", "description": "HH:MM format" },
"customer_name": { "type": "string" },
"customer_phone": { "type": "string" }
},
"required": ["date", "time", "customer_name"]
}
},
"endpoint": {
"url": "https://api.example.com/appointments/book",
"method": "POST",
"headers": { "X-Api-Key": "key" }
}
},
{
"type": "function",
"function": {
"name": "cancel_appointment",
"description": "Cancel an existing appointment",
"parameters": {
"type": "object",
"properties": {
"confirmation_number": { "type": "string" }
},
"required": ["confirmation_number"]
}
},
"endpoint": {
"url": "https://api.example.com/appointments/cancel",
"method": "POST",
"headers": { "X-Api-Key": "key" }
}
}
]
}在通話開始時執行工具
工具亦可在每次電話通話開始時自動執行, 於智能體說出第一句話前完成,讓問候語可使用結果。常見情況是根據來電者號碼查詢 CRM:「歡迎回來,Arthi!你想要平日常點的訂單嗎?」
在控制台中,開啟 API 連接,並將 執行時機 設為
每次電話通話開始時,然後填寫每個參數所需的值。透過 API,將整合的 trigger 設為
call_start,並設定其 call_start_arguments
(API 連接),或為內嵌工具加入 call_start
區塊:
{
"type": "function",
"function": {
"name": "get_contact_by_phone",
"description": "Look up a customer by phone number.",
"parameters": {
"type": "object",
"properties": {
"business_id": {"type": "string"},
"phone_number": {"type": "string"}
},
"required": ["business_id", "phone_number"]
}
},
"endpoint": {"url": "https://crm.example.com/contacts/lookup"},
"call_start": {
"arguments": {
"business_id": "a0a81c23",
"phone_number": "{{caller_number}}"
}
}
}由於通話開始時沒有人會填寫資料,因此引數必須為每個必填參數提供值。值可以是字串、數字或布林值。 系統會以純文字儲存及傳回這些值,智能體亦可看見,因此請將 API 金鑰等機密資料保留在連接的標頭中,而非填寫在此處。字串可使用以下佔位符:
| 佔位符 | 值 |
|---|---|
{{caller_number}} | 通話另一方的 E.164 格式號碼,例如 +61402122887:來電通話中的來電者,外撥通話中的被叫方 |
{{caller_number_national}} | 同一號碼的所屬國家本地格式,不含空格,例如 0402122887 |
{{agent_number}} | 智能體本身的號碼 |
運作方式:
- 此請求與智能體自行呼叫工具時發送的請求相同(相同的 endpoint、標頭、請求格式及簽名)。
- 工具會在通話開始時啟動,並會在播放任何接通提示音、 開場提示或錄音通知期間執行。問候語會由該時點起最多等待約 3 秒。如結果較慢,結果一到達便會提供給智能體, 供餘下通話使用。外撥通話會在撥出時啟動,因此每次嘗試均會執行, 包括無人接聽的嘗試。
- 如智能體設定為由來電者先說話,便沒有問候語需要 等待;結果一到達,智能體便會取得。
- 結果會作為整段通話的內容提供給智能體。在提示詞中告訴 智能體如何使用;否則不會讀出結果。
- 如工具失敗或逾時,智能體會如常向來電者問候, 並不會提及此事。
- 智能體仍可在通話較後時間自行呼叫工具。
- 此功能會在電話通話中執行,包括從控制台撥打至你電話的測試通話, 以及 AI 模擬;AI 模擬會將模擬來電者的號碼傳送至你的 endpoint。此功能不會在瀏覽器 Talk 測試或網頁小工具 工作階段中執行,因為兩者沒有來電者號碼;亦不會在來電顯示被 隱藏的通話,或設有步驟的智能體中執行。
- 每個智能體最多可同時執行三個通話開始工具。
在提示詞中提及結果,讓智能體知道如何使用,例如: 「如通話開始查詢找到來電者,請以其名字問候。」
最佳實務
撰寫清晰描述
description 欄位可協助 AI 理解何時使用工具。請具體說明工具的功能及適用時機。
妥善處理錯誤
回傳 AI 能夠理解的錯誤訊息:{"error": "No slots available for that date"},而非一般的 500 錯誤。
保持回應精簡
只傳回 AI 繼續對話所需的內容。工具結果會保留在對話中,並於其後每一輪重新讀取,因此過大的結果會增加通話餘下部分的成本和延遲。超過 100,000 個字元的結果會縮減為 AI 知道並不完整的預覽,而在非常長的通話中,較早的結果可能會被捨棄(AI 可再次呼叫工具)。新增參數,讓 AI 每次只可查詢一個項目或類別,並將選單或目錄等大型參考內容放入知識庫。控制台中的 傳送測試請求 會顯示每個結果的大小,並在結果過大時發出警告。
審慎使用必填欄位
只在確實必要時才將欄位標示為 required。AI 會在呼叫工具前向使用者索取必填資料。