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

Connect tools & data

將 ThunderPhone 用作 MCP 伺服器

透過 Claude、ChatGPT、Claude Code、Codex、Cursor、VS Code 或其他支援 Streamable HTTP 的 MCP 用戶端,建立、測試、驗證及營運 ThunderPhone 語音智能體。

ThunderPhone 透過以下網址提供 Streamable HTTP Model Context Protocol 伺服器:

https://api.thunderphone.com/v1/mcp

這與將遠端 MCP 伺服器連接至語音智能體的方向相反:

方向結果
遠端 MCP 伺服器 → ThunderPhone 智能體語音智能體可呼叫遠端伺服器的工具。
ThunderPhone → 你的 MCP 客戶端你的編碼智能體可建立、測試及操作 ThunderPhone。

驗證身分

目錄用戶端預設使用 OAuth:登入、選擇機構,並批准所要求的權限。你可在 設定 → 安全性 → 你已連接的應用程式 中中斷連接。更改或重設密碼,或更改帳戶電郵地址,亦會撤銷連接,因此之後請重新連接用戶端。

如用戶端設定為使用 API 金鑰,請在 整合 → API 金鑰 下建立 sk_live_ 金鑰,並以 THUNDERPHONE_API_KEY 向你的 MCP 用戶端提供該金鑰。金鑰會綁定至單一機構;由其他機構擁有的 ID 會被視為找不到。

處理 PHI 的機構

如果你的機構通話可能包含受保護健康資訊(PHI),原因是你與 ThunderPhone 簽訂了 BAA,或你的智能體被指定為處理 PHI,上述 URL 絕不會傳回通話內容:逐字稿、錄音、評分、通話清單、匯出資料、活動成效、通話分析及洞察、根據真實通話建立的對話,以及重播結果。這些工具會傳回包含 code: "phi_content_unavailable" 的錯誤。建立、測試及設定智能體仍可如常進行。

該 URL 列於公開助理目錄中,而這些目錄可能不會承載 PHI。若你的機構已與助理供應商簽訂 BAA,且該 BAA 涵蓋你所使用的工作區:

  1. 機構管理員在 ThunderPhone 開啟 機構 → 一般 → AI 助理存取權 並確認該涵蓋範圍。
  2. 改為使用以下 URL,將助理連接為自訂連接器:
https://api.thunderphone.com/v1/mcp/baa

屆時可在該處取得通話內容,包括可能包含 PHI 的通話。撤回確認後,助理在下一次請求時便無法再取得這些內容。你的機構判定為不含 PHI 的通話可透過任一 URL 取得。

CLI 及 stdio 替代方案

ThunderPhone CLI 可在保留不相關伺服器的同時,寫入客戶端設定:

npx -y @thunderphone/mcp setup --client cursor --api-key-env THUNDERPHONE_API_KEY
npx thunderphone mcp setup --client claude-desktop --scope user

全域安裝 @thunderphone/mcp 後,請使用 thunderphone-mcp setup 並套用相同選項。設定支援 Claude Code、Codex、Cursor、VS Code、Gemini、Claude Desktop 及 Windsurf。建議使用直接 HTTP;Desktop 則使用 stdio。

如客戶端支援 stdio,請設定 command: "npx",並使用 args: ["-y", "@thunderphone/mcp"]。此包裝程式會先使用 THUNDERPHONE_API_KEY, 然後使用 thunderphone login 的憑證並更新已過期的權杖,最後透過 mcp-remote 使用 OAuth。裝置登入及 OAuth 需要 API 已啟用相應的 OAuth; API 金鑰途徑則不需要。直接 HTTP 設定不會讀取 CLI 憑證儲存庫;如要重用裝置登入,請使用 stdio 包裝程式。

以上為下方手動客戶端設定的替代方案。

客戶端設定

Claude 和 ChatGPT 透過 OAuth 登入,無需使用 API 金鑰。如你尚未擁有 ThunderPhone 帳戶,請在登入頁面選擇 建立帳戶;完成電郵驗證後,你將返回授權確認畫面。

Claude(網頁版、桌面版及流動版)

  1. 開啟 自訂 → 連接器(舊版本為 設定 → 連接器)。如 ThunderPhone 顯示於連接器目錄中,請選擇它。否則請選擇 新增自訂連接器,將其命名為 ThunderPhone,並輸入 https://api.thunderphone.com/v1/mcp。
  2. 選擇 連接,登入 ThunderPhone,選取組織,然後批准權限。
  3. 在對話中,從工具選單啟用 ThunderPhone,並提出你的需要,例如「列出我的智能體」。

Claude 首次使用每項工具前均會詢問。若要略過大部分提示,請開啟 自訂 → 連接器 → ThunderPhone,並將 唯讀工具 設為永遠允許。這些工具只會查閱資料:智能體、通話、逐字稿、餘額及文件。如你希望在每項變更發生前查看詳情,請將 寫入/刪除工具 保持為需經批准。

自訂連接器需要付費 Claude 方案。使用團隊及企業方案時,擁有者必須先在組織的連接器設定中新增連接器,其後每位成員再連接自己的 ThunderPhone 帳戶。

Claude 有何不同

Claude(連接器及 Claude Code 外掛程式)遵循 Claude 連接器目錄的政策,因此可用工具較少:

  • 每通電話及短訊均須逐一確認。 place_call 及 send_sms 會先傳回預覽資訊(包括智能體、來電及受話號碼,以及短訊內容)和 confirmation_token;在你確認後,Claude 使用該權杖再次提出請求前,不會撥出電話或傳送短訊。
  • 不支援宣傳活動管理。 create_campaign、add_campaign_contacts 及 campaign_action 不可使用;請在控制台建立、載入及啟動宣傳活動。list_campaigns、get_campaign_stats 及 check_campaign 仍可使用。
  • 不支援 test_integration。 請在控制台的整合頁面測試整合請求。
  • preview_voice 會播放固定的示範問候語,使用你選擇的語音及語言;不會朗讀自訂文字。
  • list_voices 及 list_agents 會傳回摘要;get_agent 則提供智能體的完整設定。

AI 披露聲明

ThunderPhone 智能體撥出或接聽的每通電話,開首均會播放 AI 披露聲明。預設內容為「此通電話正在與 AI 助理進行,並會被錄音及轉錄。」除非機構管理員已先在控制台記錄已簽署的聲明,否則無法關閉此功能(將 consent_announcement_enabled 設為 false,或將 ai_live_processing_disclosure_override 關閉);此限制適用於任何用戶端,包括 Claude。

ChatGPT

  1. 如 ThunderPhone 顯示於 ChatGPT 應用程式目錄中,請選擇並連接。
  2. 否則,開啟 設定 → 應用程式及連接器 → 進階設定,啟用 開發人員模式,然後以網址 https://api.thunderphone.com/v1/mcp 及 OAuth 驗證建立連接器。
  3. 登入 ThunderPhone,選取組織,並批准權限。從工具選單將 ThunderPhone 加入對話。

刪除智能體或電話號碼、捨棄草稿、啟動推廣活動,以及發送可寫入外部系統的測試請求時,兩個應用程式均會要求再次確認;詳見確認破壞性操作。

Claude Code

claude mcp add --transport http thunderphone https://api.thunderphone.com/v1/mcp \
  --header "Authorization: Bearer $THUNDERPHONE_API_KEY"

Codex

將以下內容加入 ~/.codex/config.toml:

[mcp_servers.thunderphone]
url = "https://api.thunderphone.com/v1/mcp"
bearer_token_env_var = "THUNDERPHONE_API_KEY"

Cursor

建立 .cursor/mcp.json:

{
  "mcpServers": {
    "thunderphone": {
      "url": "https://api.thunderphone.com/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${env:THUNDERPHONE_API_KEY}"
      }
    }
  }
}

Claude Desktop

在 Claude Desktop 設定中新增 mcp-remote 橋接:

{
  "mcpServers": {
    "thunderphone": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.thunderphone.com/v1/mcp",
        "--header",
        "Authorization: Bearer ${THUNDERPHONE_API_KEY}"
      ],
      "env": {
        "THUNDERPHONE_API_KEY": "sk_live_YOUR_API_KEY"
      }
    }
  }
}

VS Code

建立 .vscode/mcp.json,並透過 VS Code 的輸入提示輸入金鑰:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "thunderphone-api-key",
      "description": "ThunderPhone organization API key",
      "password": true
    }
  ],
  "servers": {
    "thunderphone": {
      "type": "http",
      "url": "https://api.thunderphone.com/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${input:thunderphone-api-key}"
      }
    }
  }
}

工具

每項工具均附有 MCP 註釋。表格中,R 表示唯讀、D 表示破壞性操作、I 表示冪等,以及 O 表示開放世界/網絡互動。破折號表示未設定提示。

連線

工具主要參數註釋功能
get_connection_identity—R, I驗證憑證,並傳回其組織及安全的憑證中繼資料。

智能體

工具主要參數註釋功能
list_agents—R, I列出智能體。
get_agentagent_idR, I取得一個智能體。
create_agent智能體設定—建立智能體。採用與 update_agent 相同的設定,包括 steps、handoffs、intro_clip 及 intro_ring_count。
update_agentagent_id、已變更欄位、可選的 prompt_edits、expected_prompt_sha256D在智能體草稿中暫存欄位,取代草稿原有的內容。無需確認步驟即可執行:已部署的智能體在執行 deploy_agent 前不會變更,而 discard_agent_draft 會還原草稿。你亦可設定 max_hold_seconds、system_tool_settings 及 words。如要變更提示詞的部分內容,請傳送 prompt_edits(參閱就地編輯提示詞)。
deploy_agentagent_id、可選的 if_updated_atD, I將草稿推送至正式環境。
discard_agent_draftagent_id、可選的 if_updated_at、第二次請求時的 confirmation_tokenD, I捨棄暫存的變更。分兩個步驟執行,參閱確認破壞性操作。
duplicate_agentagent_id、可選的 name—在組織內複製智能體。
delete_agentagent_id、第二次請求時的 confirmation_tokenD, I永久刪除智能體。分兩個步驟執行。
list_agent_versionsagent_idR, I列出已部署的設定版本。
list_prompt_revisionsagent_id、可選的 source、limit、offsetR, I列出智能體提示詞文字的每項變更,包括草稿;每項均附有與其取代版本的差異比較。當你的連線可使用智能體迭代工具組時提供此功能(見下文)。
review_promptagent_id、可選的 prompt、previous_prompt、quote_id、max_cost_cents—根據提示詞風格指南審核草稿提示詞(或你傳送的文字)。每項發現均會引用相關段落、列出指南規則,並提供尋找及取代的編輯建議;結果亦會列出提示詞要求的行為及其穩定識別碼、是否需要重構,以及就智能體本身的提示詞而言,其測試對話是否需要更新。不會變更智能體;清單會隨其提示詞修訂版本儲存。此功能需付費,因此不標示為唯讀:先以 dry_run 取得報價,然後使用其返回的 quote_id 和 max_cost_cents,在不帶 dry_run 的情況下再次執行。這些付費執行現時會與其他工具組執行共用同一組織的工具組配額。當你的連線可使用智能體迭代工具組時提供此功能(見下文)。
refactor_promptagent_id、可選的 prompt、inventory、instructions、quote_id、max_cost_cents—按照風格指南的結構重寫提示詞,並將每項行為標示為保留、合併、改寫或移除。返回新文字及差異比較,並預設重新讀取內容以報告 behavior_changes(新增、移除或變更)及 behavior_preserved;使用 update_agent 套用。此功能需付費:先以 dry_run 取得報價,然後使用其返回的 quote_id 和 max_cost_cents 執行一次。當你的連線可使用智能體迭代工具組時提供此功能(見下文)。
list_reusable_instructions—R, I列出可重用指示:透過 update_agent 的 reusable_instruction_ids 附加至多個智能體的共用提示詞規則。
create_reusable_instructionname、content—建立未附加的可重用指示。僅限管理員。

電話號碼及電訊商

工具主要參數註釋功能
list_phone_numbers—R, I列出組織的號碼及路由設定。
get_phone_number_limits—R, I取得受管理號碼的使用量及限制。
provision_phone_number可選 area_code、city、state、idempotency_keyD, O購買由 ThunderPhone 管理的入站號碼。
list_voip_connections—R, I列出已連接的客戶電訊商。
search_voip_numbersconnection_id、country、type、可選 area_codeR, I, O搜尋電訊商號碼庫存。
import_voip_numbersconnection_id、numbersD, O匯入已在電訊商持有的號碼。
update_phone_numberphone_number_id、路由/標籤/webhook 欄位D更新號碼路由設定,包括智能體指派。
delete_phone_numberphone_number_id、confirm、可選 release_at_provider、第二次請求時的 confirmation_tokenD, I, O釋放號碼。分兩個步驟。
get_voip_setup_session可選 session_idR, I讀取引導式電訊商設定(狀態、檢查清單、正在等候回答的問題),或列出尚未完成的設定。設定必須在控制台開始,因為需要電訊商密碼。僅限管理員。
answer_voip_setup_questionsession_id、question_id、answerO將使用者的答案傳送至設定程序。密碼、測試通話同意、伺服器地址、使用者名稱,以及允許 ThunderPhone 登入供應商帳戶,只可在設定精靈中回答;如屬此類問題,工具會傳回精靈連結而不會傳送任何內容。
save_voip_setupsession_id、可選 name、第二次請求時的 confirmation_tokenD, I, O儲存已連接的草稿連線,以便使用。分兩個步驟。
check_phone_numberphone_number 或 phone_number_idR, I, O根據證據診斷組織自有的其中一個號碼:路由、連線、驗證、近期電訊商及測試通話,以及電訊商將其轉送到何處。

SMS

工具主要引數註釋功能
send_smsfrom_number, to, body, idempotency_keyD, I, O透過已連接嘅 Twilio 或 Telnyx 號碼傳送一則純文字 SMS。

通話

工具主要參數註釋功能
list_calls可選篩選條件、limit、offsetR、I使用 REST 通話記錄篩選條件列出通話,包括 exclude_test_calls。
get_callcall_idR、I取得通話狀態及中繼資料。
get_call_transcriptcall_id、可選 liveR、I取得通話逐字稿。
get_call_audio_urlcall_id、可選 downloadR、I、O傳回已簽署的音訊 URL;絕不會透過 MCP 串流傳送音訊。
get_call_gradecall_idR、I取得最新通話評分。
place_callagent_id、from_number、to_numberD、O撥出一通非冪等的外撥電話。
export_calls通話篩選條件、export_formatR、I以 JSON 或 CSV 匯出最多至 REST 端點上限的資料。
get_call_analytics可選 since_days、agent_idR、I按狀態、方向、結果、評分及問題彙總真實通話,並將測試通話分開計算。
get_call_insightscall_ids(最多 10 個)R、I一次取得多通通話的評分、結果、摘要及偵測到的問題。

測試及驗證

工具主要參數註解功能
list_test_scenariosagent_idR, I列出測試情境。
create_test_scenarioagent_id, title, scenario_prompt, 可選條件—建立情境。
generate_test_scenariosagent_id, 可選 count, include_edge_cases, localeO根據智能體提示生成情境。
run_agent_testsagent_id, channel, consent_to_charge, 可選選擇/矩陣D, O透過網頁或電話執行情境。
get_test_runagent_id, batch_idR, I取得批次狀態及各情境結果。
test_my_agentagent_id, consent_to_charge, 可選 scenario_ids, count, wait_secondsD, O在一次呼叫中測試智能體:執行其已儲存的情境(沒有情境時會生成部分情境),並最多等待一分鐘取得判定結果;或回傳供 get_test_run 使用的 batch_id。收費方式與 run_agent_tests 相同。
test_in_textagent_id, callers(1 至 3 個描述), 可選 version, directionO免費文字測試:模擬來電者透過真實流程以文字與智能體草稿(或已發佈版本)對話,約一分鐘後傳回逐字稿。工具結果為模擬結果。
run_simulationagent_id, consent_to_charge, 可選 scenario_prompt, direction, languageD, O在 AI 來電者與智能體草稿之間啟動一次模擬電話通話,讓人員可旁聽變更效果。回傳狀態為 in_progress 的執行作業。智能體有錄音時會錄製通話,並會在通話結束後評分。收費方式與測試通話相同,會優先使用免費測試額度。
get_simulationsimulation_idR, I取得模擬通話的狀態,以及在結束後產生的內容:智能體有錄製通話時提供短期有效的錄音 URL 和逐字稿,完成評分後提供評分結果(此前為 null)。
list_validation_runsagent_idR, I列出近期草稿驗證執行作業。
get_validation_statusagent_idR, I取得最新驗證狀態及草稿匹配結果。
list_conversationsagent_id, 可選 split, sourceR, I列出用於測試智能體的對話。需要智能體迭代工具組。
get_conversationconversation_idR, I取得一個測試對話及其目前的對話輪次。需要智能體迭代工具組。
get_conversation_revisionsconversation_id, 可選 limit, offsetR, I列出測試對話的每個修訂版本:變更方式和原因(因提示變更而重新整理、從較早修訂版本還原)、新增、移除和變更的行為、移動或淘汰的範例,以及行差異。需要智能體迭代工具組。
generate_conversationsagent_id, 可選 count, styleO根據智能體草稿編寫模擬測試對話,並將其中最困難的時刻轉換為附有答案鍵的驗證範例。先以 dry_run 取得報價;實際執行需要其 quote_id 和 max_cost_cents。需要智能體迭代工具組。
import_conversationsagent_id, 可選 since_days, max_callsO將智能體近期通話轉換為測試對話(每位來電者最多兩個,略過未錄音通話),並將其中最困難的時刻轉換為範例。先以 dry_run 取得報價;實際執行需要其 quote_id 和 max_cost_cents。需要智能體迭代工具組。
refresh_conversationsagent_id, 可選 conversation_ids, from_prompt_revision_idO在新增、移除或變更行為後,將智能體測試對話更新至目前提示:重新指向、還原較早修訂版本(包括真實音訊),或重寫過時的對話輪次,並淘汰來電者輪次已不存在的範例。先以 dry_run 取得報價;實際執行需要其 quote_id 和 max_cost_cents。需要智能體迭代工具組。
get_conversation_jobjob_idR, I取得生成、匯入或重新整理工作:狀態、截至目前相對其上限的成本,以及已編寫或重新整理的內容。需要智能體迭代工具組。
run_replaysagent_id, 可選 overrides, split, engine, sample_size, sample_seed, max_cost_cents, quote_id, dry_runD, O在智能體草稿下,或在候選提示、語音或方案等覆寫設定下,重播智能體範例的樣本,並根據範例的答案鍵判斷每個回覆。精確重播會如同即時通話般播放該輪次錄製的音訊;通過率會按引擎列出。PHI 通話的重播會以 PHI 方式執行,無法執行的設定(ElevenLabs 語音、實驗性產品)會被拒絕。dry_run 會傳回估算、所抽取的 sample_seed 及 quote_id;實際執行會以該 quote_id 和 sample_seed 提交相同請求,並提供硬性上限 max_cost_cents:每項請求在送出前會預留其成本上限,無法符合上限時執行作業會停止而不會送出,因此每名工作者應預留估算中的 largest_reservation_cents 餘額。精確重播會預留最壞情況成本;一般輪次中,每個進行中的重播約為 85 美仙至 $1.25(可同時執行兩個),實際成本則只需數美仙;執行作業會按重播實際成本收費,因此設定 max_cost_cents 時應預留空間。精確重播會在足以應付一般輪次加上一次與正式環境相同類型重新執行的預算下運行(再次競逐回覆及監察重試);需要更多預算的輪次會記錄為錯誤 replay_budget_exhausted,並以 budget_exhausted 獨立統計、不計入通過率,而且在測試分組中不會消耗 cohort。在測試分組中,若某 cohort 包含錄製的來電者音訊,而設定並非 Bolt v2,則會被拒絕(test_needs_exact_replay)並保持未使用:請在開發分組中量度該設定。需要智能體迭代工具組。
compare_configsagent_id, configs(2 至 4 個,第一個為基準), 可選 sample_size, sample_seed, max_cost_cents, quote_id, dry_runO在每個設定下重播相同範例,並按引擎報告通過率、相對基準已修正及出現問題的範例、首段音訊延遲、來電者等待確認訊號、提示音或靜音的頻率,以及每輪成本。與 run_replays 一樣,先以 dry_run 取得報價。只適用於開發分組:在測試分組中會被拒絕(comparison_dev_only);先在開發分組比較,再以 run_replays 量度所選設定。需要智能體迭代工具組。
get_replay_runrun_id, 可選 include_traceR, I取得重播執行作業的總計、變動及每個範例的結果,以及其比較群組。需要超出預算的精確重播會以 budget_exhausted 獨立統計,不計入通過率。需要智能體迭代工具組。
create_talk_linkagent_id, 可選 variant_id, language, expires_in_minutesO建立單次使用連結,使用者可在瀏覽器開啟連結並與智能體目前草稿對話,與控制台的 Talk 按鈕相同。連結預設於 30 分鐘後到期(最多 120 分鐘);對話收費方式與 Talk 測試通話相同。參閱 Talk 連結。

標示為需要智能體迭代工具組的工具均屬於該工具組;工具組在 Beta 期間按機構啟用,未啟用時,這些工具會回傳 feature_not_enabled,並說明下一步操作。每個智能體的對話均屬於其開發分組或測試分組。測試分組用於衡量變更,而非調整變更,因此對話工具對測試分組的對話只會回傳其 ID、分組、來源、狀態及計數。測試分組上的重播執行會重播整個測試群組(會忽略 sample_size 及 sample_seed),並按每個範例資料容許的引擎執行;引擎會在執行前根據範例設定(已錄製的來電者音訊使用精確重播,純文字範例使用文字;Bolt v2 以外的設定沒有精確路徑,因此含有已錄製音訊的群組會以 test_needs_exact_replay 被拒絕,並保持未使用;會省略 engine 或設為 auto,因為 exact 或 text 會以 test_engine_per_example 被拒絕,且不會回退至文字),並且只會按引擎回傳總計:通過率、按嚴重程度及類型劃分的失敗、延遲及成本。第一個儲存重播結果會使用該群組,因此下一次測試執行無論使用任何提示詞,都會取用另一個群組;如沒有剩餘群組,便會以 no_test_cohort 被拒絕(匯入通話或產生對話可補充新的群組)。在儲存任何結果前已結束的執行(Core 無法精確重播其音訊範例、exact_replay_unavailable、其重播容量仍然忙碌、core_busy,或每個回合均已耗盡其預算、replay_budget_exhausted)不會使用該群組。在開發分組上,如 Core 無法執行精確重播,會回退至文字,而該執行會標示為 degraded。比較只會在開發分組上執行。每個收費工具均接受其試行的 quote_id,每個 ID 只可用於一次執行:執行開始時會永久使用一次;如啟動被拒絕或在此之前失敗,該 ID 仍可使用;如執行在此之後失敗,會顯示相關狀態,並須以新的試行取得新的 quote_id 後重新執行。使用 OAuth 時,review_prompt 及 refactor_prompt 需要 agents:write 範圍,包括試行;對話及重播工具則需要 testing:write 才可執行。使用者可在控制台查看完整測試分組。來電者屬於某智能體測試分組的通話會被保留,因為該通話是測試集的一部分。在已啟用工具組的機構中,list_calls、get_call、get_call_transcript、get_call_audio_url、get_call_grade 及 export_calls 只會將該通話回傳為 {"call_id", "start_time", "held_out": true}(匯出列中以 started_at 取代 start_time),不會提供其逐字稿、錄音、歷史、評分或報告;通話的所有其他欄位均不存在,因此應先透過其 held_out 讀取保留列,再處理其他資料。REST API 對 API 金鑰及 OAuth 權杖亦採取相同處理方式;其涵蓋多個通話的檢視(報告摘要、問題群組、調查、流程報告)不會將保留通話納入計數、群組及樣本,亦會隱藏模型從中產生的任何文字。對保留通話的寫入操作(評分、將其提升為測試情境、重新產生回合)會以 held_out_call 被拒絕。有人從保留通話提升的測試情境,會從 list_test_scenarios 及測試執行中回傳為 {"id", "held_out": true};由其產生的模擬執行,則會從 get_test_run 及模擬工具回傳為 {"id", "scenario_id", "held_out": true};其模擬通話亦會被保留,但測試執行仍會執行該情境。從保留來電者通話複製的開發對話、範例或重播結果(分組按智能體劃分,因此該來電者可能位於另一個智能體的測試分組)會如測試分組項目般讀取。使用者可在控制台完整查看保留通話;管理員可讓一個 API 金鑰完整查看這些通話(include_held_out_calls,預設關閉,僅可在控制台設定),供需要每一通通話的整合使用;MCP 永不使用此設定。Webhook 不受影響。未啟用工具組的機構不會看到 held_out 欄位,亦不會有任何變更。

generate_conversations、import_conversations 及 refresh_conversations 會使用模型點數。請先以 dry_run: true 呼叫:回應會逐步提供成本報價,附帶 quote_id,而不會執行任何操作。報價會按一般規模計算執行期間可能發出的每個請求。實際執行需要該 quote_id(15 分鐘後失效,而且只適用於相同的引數)及 max_cost_cents,即硬性上限:每次請求前,工作會預留該請求可能產生的最高成本;如不符合上限,便會停止而不發出該請求,並保留已寫入的內容。由於這項預留機制,執行結束時可能仍有部分上限未被使用;報價中的 largest_reservation_cents 會說明需要預留多少緩衝額度。模擬來電者會根據智能體的提示建立;style: "adversarial" 會建立針對提示詞薄弱環節的高難度來電者,而這些對話一律歸入開發分組。target: "changed_behaviors" 會讓來電者聚焦於上次編輯提示詞時變更的行為。每個智能體同一時間只能執行其中一項工作或一次重播執行,因此重新整理不會變更重播執行中的範例;如在另一項工作執行期間啟動,會傳回 job_active、replay_run_active 或 conversation_job_active,並說明需要等候的項目。

在新增、移除或變更行為的提示詞編輯後,智能體草稿上的 review_prompt 會報告有多少測試對話是根據包含其他行為的提示詞所建立(conversations.refresh_suggested)。其後,refresh_conversations 會將這些對話更新至草稿,讓開發及測試集合根據新提示詞原本可能產生的歷史記錄進行評估。重新整理不會遺失任何內容:每個對話都會保留所有較早的修訂版本;當已移除的規則重新加入時,會還原該規則原先存在時的修訂版本,包括真實來電者音訊。由程式開發智能體啟動的重新整理,會將測試分組對話及從保留通話複製的對話排除於選取、報價、進度及成本之外;如在 conversation_ids 指定其中一個,會傳回 403 test_conversation。使用者可從控制台重新整理這些對話,而該工作的結果只會向程式開發智能體顯示其識別碼及數量。重新整理改寫其歷史記錄、回覆或答案索引鍵的 active 範例,會返回 pending_review,並標示為 refreshed_needs_review。重新整理的報價會將每個讀取的對話,按如同需要改寫般計價,並按每次模型呼叫的輸出上限計算;報價只適用於取得報價時的提示詞及對話:如任一項目在執行前變更,請重新取得報價;如提示詞在執行期間變更,工作會以 failed 停止,並保留已重新整理的內容。

知識庫

工具主要參數註釋功能
list_knowledge_bases—R, I列出知識庫。
create_knowledge_basename、可選的 description—建立知識庫。
add_knowledge_documentknowledge_base_id、name、content—新增文字或 Markdown。
import_knowledge_urlurl、可選的 nameO將公開頁面加入佇列,以便安全擷取。
search_knowledgeknowledge_base_id、queryR, I透過正式環境檢索功能搜尋。

整合、webhook 及遠端 MCP 伺服器

工具主要參數註解功能
list_integrations—R, I列出 HTTP 函數整合。
create_integrationdisplay_name、函數 spec、可選端點欄位—建立 HTTP 工具。請在控制台新增驗證標頭。
test_integrationurl、可選方法/主體/逾時設定、包含 header_names 的 integration_id、第二次請求使用的 confirmation_tokenD, O傳送受限制並受 SSRF 保護的測試請求。已儲存的標頭值會從整合設定中填入,並只會傳送至其所屬主機。POST(預設)、PUT、PATCH 及 DELETE 均為兩步操作;GET 會立即執行。
list_webhook_endpoints—R, I列出已簽署的 webhook 端點。
list_webhook_deliveries可選 agent_id、可選 endpoint_idR, I列出近期不含載荷的 webhook 傳送結果。
create_webhook_endpointlabel、url、可選事件/狀態O建立已簽署的 webhook 端點。
copy_webhook_endpointendpoint_id、target_agent_idI將智能體的 webhook(包括簽署密鑰)複製至伺服器上的另一個智能體。僅限管理員使用。
test_webhook_endpointendpoint_idO透過正常傳送流程傳送模擬事件。
list_mcp_servers—R, I列出可供語音智能體呼叫的遠端伺服器。
create_mcp_serverdisplay_name、urlO註冊並同步遠端伺服器。需要驗證標頭的伺服器請在控制台新增。
sync_mcp_server_toolsserver_idD, O重新整理遠端伺服器的工具目錄。

推廣活動

工具主要參數註解功能
list_campaigns—R、I列出外撥活動。
create_campaign活動欄位—建立草稿活動。
add_campaign_contactscampaign_id、contacts—最多新增 5,000 個 JSON 聯絡人。
campaign_actioncampaign_id、action、可選的 consent_to_charge、第二次請求中的 confirmation_tokenD、O執行 start、pause、resume 或 stop。start 及 resume 需要兩個步驟;pause 及 stop 會立即執行。
get_campaign_statscampaign_idR、I取得計數器及最近結果。
check_campaign可選的 campaign_id、contact_phone_number、contact_statusR、I說明活動未有撥出的原因:其所屬時區的撥號時段、目前應撥打的聯絡人,以及阻止撥號的因素。

機構設定及已封鎖來電者

工具主要參數註釋功能
get_org_settings—R, I讀取時區、營業時間、測試號碼、通話結果標籤、狀態名稱及已關閉的警示,並附帶 updated_at。
update_org_settings已變更的設定、if_updated_at、要求時提供 confirmation_tokenD, I變更設定(僅限管理員)。清單及物件會取代已儲存的值。關閉警示或新增測試號碼均需兩步確認。結果包含舊值,以供還原。
get_account_limits—R, I取得平台限制,並顯示此機構專屬的值。
list_blocked_callers可選 number、searchR, I列出已封鎖的來電號碼。
block_callersnumbers、可選 note、第二次請求時提供 confirmation_tokenD, I在任何智能體接聽前拒絕來自這些號碼的來電。需兩步確認,僅限管理員。
unblock_callersnumbers、第二次請求時提供 confirmation_tokenD, I從封鎖清單中移除號碼。需兩步確認,僅限管理員。

get_org_settings、update_org_settings 及 get_account_limits 需要 org:read 或 org:write OAuth 範圍;在這些功能推出前建立的連接,會在首次使用時要求批准該範圍。

功能、協助及匯入

工具主要參數註釋功能
get_supported_languages—R, I列出智能體可說的語言及其代碼。
get_agent_capabilities—R, I說明智能體可在通話中執行的操作,以及可用的設定和整合。
escalate_to_humansummaryO向 ThunderPhone 團隊尋求協助。他們會在 ThunderPhone 中回覆。對於可能處理 PHI 的機構,只有中性備註會傳出 ThunderPhone。
request_featuretitle、request、detailsO向 ThunderPhone 團隊提交功能要求。每個機構每日最多三項。
start_agent_importplatformR, I傳回控制台連結,你可在該處輸入 Vapi、Retell、ElevenLabs 或 Bland 金鑰並選擇智能體。沒有任何工具會接收該金鑰。
get_agent_import可選 import_idR, I列出最近的匯入作業,或顯示單一匯入作業的狀態及已對應的智能體。
commit_agent_importimport_id、可選 item_idsO在背景根據已準備好的匯入作業建立智能體。僅限管理員。

語音、帳單及文件

工具主要參數註解功能
list_voices—R, I列出語音及支援的語言。
preview_voicevoice, language, textO產生範例並傳回已簽署 URL。
list_voice_clones—R, I列出自訂語音複製。
get_billing_summary—R, I取得餘額及具權威性的方案價格;不提供任何付款異動操作。
search_docsquery、可選 limitR, I, O搜尋公開文件索引。
get_doc_pagepathR, I, O擷取一個公開 Markdown 文件頁面。

有關智能體、通話、號碼、推廣活動或設定的結果均附有 web_url,即相應的控制台頁面,你可在 ThunderPhone 開啟該頁面,或在該處繼續使用 Zeus。

所有產品工具均使用與公開 API 相同的 REST 程式碼路徑。因此,REST 驗證、組織範圍限制、角色、帳單准入、配額、TCPA 確認、供應商安全措施及審計行為均同樣適用。

就地編輯提示詞

update_agent 可在無需重新傳送完整文字的情況下,修改草稿提示詞的一部分。prompt_edits 是按順序排列的尋找及取代配對清單,格式與 review_prompt 及 refactor_prompt 回傳的格式相同:

{
  "agent_id": 123,
  "expected_prompt_sha256": "9c1f…",
  "prompt_edits": [
    {
      "find": "Ask for their name and their phone number, then tell them we will call back.",
      "replace": "Tell them we will call back, then ask for their name. Once they answer, ask for their phone number."
    }
  ]
}

伺服器會依序將編輯套用至智能體目前的草稿提示詞(如沒有草稿,則為已部署的提示詞),並透過與完整提示詞 update_agent 相同的路徑將結果寫入草稿。每個 find 必須在該次編輯開始時的提示詞中剛好出現一次。否則不會寫入任何內容,且錯誤會指出該編輯:

代碼含義處理方法
prompt_edit_not_foundfind 文字不在目前的草稿提示詞中。edit_index 指出是哪一項編輯。再次讀取智能體,並完全按照原文複製該段落。
prompt_edit_ambiguousfind 文字出現超過一次。occurrences 指出出現次數。加入更多周邊文字。
stale_promptexpected_prompt_sha256 並非目前草稿提示詞的 SHA-256:提示詞在你讀取後已變更。再次讀取智能體,根據目前文字重寫變更,並傳送其 SHA-256。
conflict伺服器讀取草稿與寫入草稿之間,有另一項寫入完成。重試;此呼叫未有變更草稿。

expected_prompt_sha256 為選填,亦可保護完整提示詞寫入。使用 review_prompt 的 prompt_sha256,或 refactor_prompt 的 source_prompt_sha256。任何會變更提示詞的呼叫,都會回傳新文字的 prompt_sha256、伺服器先讀取草稿時的 previous_prompt_sha256,以及建議使用 review_prompt 的 next_step,並將 previous_prompt 設為變更前的文字。REST API 只接受完整提示詞:使用 prompt 和 if_updated_at 呼叫 PATCH /v1/agents/{agent_id}。

確認破壞性操作

標示為 D 的工具會變更或移除項目,或開始撥打真人電話。無法復原的操作需要兩次請求。第一次請求不會作出任何變更,並會返回:

{
  "status": "confirmation_required",
  "action": "Delete agent",
  "target": { "id": 195, "name": "Front Desk Receptionist" },
  "confirmation_token": "…",
  "expires_in_seconds": 600,
  "next_step": "…"
}

助手會向用戶顯示受影響的項目並要求確認。其後會以相同參數加上 confirmation_token 再次發出請求。Token 有效期為 10 分鐘,只可使用一次(即使該次呼叫失敗亦然),而且只涵蓋一個機構、一名人員、一項工具及一組完全相同的參數,因此刪除三個智能體需要三次確認。使用 pause 或 stop 的 campaign_action 會略過此步驟,確保可以隨時立即停止正在執行的活動;使用 GET 的 test_integration 亦然。部分 D 工具可在一次請求中執行,因為 D 標示的是其影響,而非伺服器端確認:update_agent 會取代草稿原有內容(discard_agent_draft 可將其還原)、deploy_agent 會取代正式運行中的設定、update_phone_number 會重新路由實時通話、sync_mcp_server_tools 會取代遠端伺服器的工具目錄、import_voip_numbers 會將號碼重新指向你的電訊營運商、run_agent_tests 和 run_simulation 可耗用點數、send_sms 和 place_call 會聯絡真人(place_call 保留其本身的同意確認),而 provision_phone_number 會購買號碼。test_my_agent 會耗用測試點數,並需要 consent_to_charge。run_replays 同樣會產生費用;其 dry_run 報價及 max_cost_cents 上限會取代確認程序。你的 MCP 用戶端仍可能要求你批准這些操作。

部分可復原的變更仍需確認:block_callers、unblock_callers 及 save_voip_setup 一律需要確認;update_org_settings 在停用警示或新增測試號碼時需要確認;而 update_agent 則在其 attention_reasons 停用智能體其中一項警示時需要確認。它們的 next_step 會要求你確認確切變更,而非警告該變更無法復原。

入門提示

prompts/list 提供十二個可重複使用嘅工作流程:

  • create_inbound_receptionist
  • run_agent_tests
  • buy_and_attach_number
  • review_low_grade_calls
  • add_url_to_agent_knowledge
  • improve_agent_from_calls
  • check_change_before_deploy
  • test_my_agent
  • diagnose_phone_number
  • why_campaign_not_calling
  • call_report
  • import_agents

使用 prompts/get,並提供列出的提示名稱及其宣告的參數,即可取得可直接執行的使用者訊息。

資源

resources/list 提供公開的快取參考資料:

URI內容
thunderphone://docs/llms.txt公開文件索引。
thunderphone://docs/quickstart快速入門 Markdown 文件。
thunderphone://pricing目前公開定價的 Markdown 文件。
thunderphone://guides/prompt-stylereview_prompt 用作核對依據的語音智能體提示詞風格指南。當中的指南 ID(例如 P1、W2)亦是檢查結果所引用的 ID。
thunderphone://guides/working-with-thunderphone助手應如何使用這些工具:分小輪次處理草稿、每次部署前檢查、任何上線或收費操作均須取得使用者同意,以及絕不要求提供機密資料。

使用 resources/read 讀取其中一項。公開擷取採用較短逾時設定、2 MiB 上限,以及 10 分鐘的程序內快取。

協定與錯誤

伺服器支援 2025-06-18 及 2025-03-26 協定版本;會回傳受支援的客戶端版本,否則選擇 2025-06-18。它實作了 initialize、ping、工具、提示、資源及通知。通知會返回 202 Accepted。此無狀態伺服器不提供 SSE 監聽器或工作階段刪除功能,因此 GET 及 DELETE 會返回 405 Method Not Allowed,並附帶 Allow: POST。

工具失敗仍會以帶有 isError: true 的成功 JSON-RPC 回應形式返回。其文字包含一句簡短說明,後接一個 JSON 區塊:

{
  "code": "insufficient_balance",
  "detail": "There is not enough prepaid balance.",
  "next_step": "Call get_billing_summary, add funds in Organization > Billing, then retry."
}

place_call 會保留獨特的 outbound_tcpa_confirmation_required: 前綴。未知的 JSON-RPC 方法會在 HTTP 200 回應中返回 -32601。MCP 2025-06-18 不支援 JSON-RPC 批次請求,並會返回明確的 -32600 無效請求錯誤。