函式工具

函式工具可讓你的 AI 智慧體在通話期間呼叫外部 API。使用它們查詢客戶資料、檢查可用時段、預約行程，或執行你的後端支援的任何操作。

運作方式

你使用結構描述定義工具（工具可接受的引數）
你提供 endpoint 設定（ThunderPhone 呼叫你的 API 的位置）——或不設定，以便在組織的網路掛鉤接收工具呼叫
通話期間，AI 會根據對話決定何時使用工具
ThunderPhone 會使用工具引數呼叫你的端點
你的 API 回應會回傳給 AI，以繼續對話

函式工具是自備 API 的方式。ThunderPhone 也提供不需要端點的平台代管工具：應用程式連線（HubSpot、Salesforce、Slack、 Google Calendar、Google Sheets、Cal.com）、 API 連線，以及 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"
    }
  }
}

函式定義

欄位	類型	必填	說明
`name`	字串	是	工具的唯一識別碼
`description`	字串	是	向 AI 說明何時使用此工具
`parameters`	物件	是	工具引數的 JSON Schema

端點設定

欄位	類型	必填	說明
`url`	字串	是	你的 API 端點 URL
`method`	字串	否	HTTP 方法（預設值：`POST`）
`headers`	物件	否	要包含的自訂標頭

endpoint 設定不會傳送至 AI 模型——它僅供 ThunderPhone 用來執行工具呼叫。

兩種呼叫路徑

你的伺服器收到哪一種請求，取決於工具是否具有 endpoint：

	具有 `endpoint` 的工具	不具有 `endpoint` 的工具
請求傳送位置	直接傳送至 `endpoint.url`	你的組織的舊版網路掛鉤 URL
內容主體	純工具引數	`telephony.tool` / `web.tool` 封裝格式
標頭	你的 `endpoint.headers` + `X-ThunderPhone-Call-ID` + `X-ThunderPhone-Signature`	`Content-Type` + `X-ThunderPhone-Signature`
簽署金鑰	組織網路掛鉤密鑰	組織網路掛鉤密鑰

兩種路徑皆為阻塞式——AI 會在說到一半時等待結果——並設有 20 秒逾時限制。請讓處理常式保持快速。混用也沒問題：在組織設有網路掛鉤 URL 的通話中，具有 endpoint 的工具會直接呼叫，其餘工具則會改由網路掛鉤處理。

直接端點呼叫

當 AI 呼叫具有 endpoint 的工具時，ThunderPhone 會向你的 URL 傳送請求：

請求標頭

POST /appointments/search HTTP/1.1
Host: api.example.com
Content-Type: application/json
X-ThunderPhone-Signature: abc123...
X-ThunderPhone-Call-ID: 987654321
X-Api-Key: your-api-key

系統一律會原樣包含你在 endpoint.headers 中設定的自訂標頭，以及兩個 ThunderPhone 命名空間標頭：

X-ThunderPhone-Signature —— 使用你的組織 webhook 密鑰作為金鑰，對確切的請求主體位元組計算的 HMAC-SHA256
X-ThunderPhone-Call-ID —— 目前的通話 ID

除非你的 endpoint.headers 覆寫它，否則系統會設定 Content-Type: application/json —— 自訂 Content-Type 會優先採用。

簽章使用來自 GET /v1/webhook 的組織層級 webhook 密鑰作為金鑰。如果你的組織從未設定過舊版 webhook，便不會有密鑰，工具呼叫將僅帶有 X-ThunderPhone-Call-ID —— 若處理常式在缺少簽章時直接失敗，就會拒絕這些呼叫。請設定舊版 webhook 以取得密鑰，或在 endpoint.headers 中放入你自己的共用密鑰。

請求主體

對於 POST / PUT / PATCH，主體僅包含工具引數（不含包裝層），並以標準化方式序列化（排序鍵值、精簡分隔符號）：

{"date":"2025-01-02","service":"consultation"}

對於 GET / DELETE，引數會作為查詢參數傳送，主體為空 —— 此時簽章會針對空位元組字串計算。請參閱驗證 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 密鑰，針對原始主體進行簽署。

已訂閱的 webhook 端點還會在每次工具執行後收到非阻塞式的 telephony.tool / web.tool 通知（無論透過哪個路徑執行），其中包含工具的回應 —— 適合用於建立稽核軌跡。請參閱事件目錄。

簽章驗證

直接工具呼叫的簽章方式與 Webhook 相同：

對完全一致的請求主體位元組計算 HMAC-SHA256（標準化 JSON——鍵已排序，無額外空白）
使用你組織的 Webhook 密鑰作為金鑰
GET／DELETE 工具會對空位元組字串簽章

import hmac
import hashlib

def verify_tool_call(body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

@app.post("/appointments/search")
async def search_appointments(request: Request):
    body = await request.body()
    signature = request.headers.get("X-ThunderPhone-Signature", "")

    if not verify_tool_call(body, signature, WEBHOOK_SECRET):
        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}

app.post('/appointments/search', express.raw({type: 'application/json'}), (req, res) => {
  const signature = req.headers['x-thunderphone-signature'] || '';
  const expected = crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(req.body)
    .digest('hex');

  if (!signature ||
      signature.length !== expected.length ||
      !crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature))) {
    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 });
});

完整範例——包括空主體情況及未設定密鑰時的注意事項——請參閱驗證 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" }
      }
    }
  ]
}

最佳實務

撰寫清楚的說明

description 欄位可協助人工智慧理解何時使用此工具。請明確說明工具的功能，以及適合使用的時機。

妥善處理錯誤

回傳人工智慧能理解的錯誤訊息：{"error": "No slots available for that date"}，而不是通用的 500 錯誤。

保持回應簡潔

僅回傳人工智慧繼續對話所需的資訊。大型酬載會拖慢回應時間。

審慎使用必填欄位

只有在確實必要時，才將欄位標示為 required。人工智慧會在呼叫工具前向使用者詢問必填資訊。

應用程式連線

平台代管的 HubSpot、Salesforce、Slack、Google Calendar、Google Sheets 和 Cal.com 工具——無需端點。

MCP 伺服器

附加 MCP 伺服器，讓智慧體呼叫其工具。

API 連線

可重複使用、可附加至智慧體的 REST 整合。

驗證 Webhook 簽章

適用於 Webhook 與工具呼叫的單一驗證輔助工具。

Webhooks

Function Tools

運作方式

工具結構描述

函式定義

端點設定

兩種呼叫路徑

直接端點呼叫

請求標頭

請求主體

回應

Webhook 模式派送

簽章驗證

範例：完整預約流程

最佳實務

相關內容

應用程式連線

MCP 伺服器

API 連線

驗證 Webhook 簽章

​運作方式

​工具結構描述

​函式定義

​端點設定

​兩種呼叫路徑

​直接端點呼叫

​請求標頭

​請求主體

​回應

​Webhook 模式派送

​簽章驗證

​範例：完整預約流程

​最佳實務

​相關內容

應用程式連線

MCP 伺服器

API 連線

驗證 Webhook 簽章

運作方式

工具結構描述

函式定義

端點設定

兩種呼叫路徑

直接端點呼叫

請求標頭

請求主體

回應

Webhook 模式派送

簽章驗證

範例：完整預約流程

最佳實務

相關內容