ThunderPhone v3 現已上線。自助開通,價格低至每分鐘 2¢。查看公告

Function Tools

函數工具

為你的 AI 智能體提供函數工具,可在對話期間呼叫外部 API——擷取客戶資料、預約、更新記錄——並支援具類型的參數。

函數工具讓你的 AI 智能體可在通話期間調用外部 API。你可用它們查詢客戶資料、檢查可用時段、預約服務,或執行後端支援的任何操作。

運作方式

  1. 以綱要定義工具(工具可接受哪些參數)
  2. 提供 endpoint 設定(ThunderPhone 在何處調用你的 API)——或不設定,以便透過組織 webhook 接收工具調用
  3. 通話期間,AI 會根據對話決定何時使用工具
  4. ThunderPhone 會連同工具參數調用你的端點
  5. 你的 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 —— 目前通話 ID
  • X-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 分鐘時限:

Python
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}
Node.js
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 會在呼叫工具前向使用者索取必填資料。


相關內容