Upfirst

連線

無需安裝任何東西。將您的客戶端指向 https://mcp.upfirst.ai，它會在首次連線時引導您登入 Upfirst。授權採用標準的 OAuth 2.1 登入流程，因此無需複製或儲存任何 API 金鑰。

此伺服器透過 streamable HTTP 運行，為您的助理提供 25 個工具，既可讀取您的帳戶，也可對其進行變更。請在下方選擇您的客戶端。

Upfirst 已收錄在 Claude 的連接器目錄中。開啟 claude.ai/directory/upfirst，新增 Upfirst，然後登入 Upfirst 並核准存取權限。它可在 Claude 桌面應用程式及 claude.ai 上運作。

改以新增為自訂連接器

1. 開啟 自訂，然後選擇 連接器。
2. 點擊 +，然後選擇 新增自訂連接器。
3. 將其命名為 Upfirst，並將下方的 URL 貼上作為遠端 MCP 伺服器 URL。
4. 將進階的 Client ID 與 Client Secret 欄位留空。
5. 點擊 新增，然後點擊 連線，登入 Upfirst 並核准存取權限。

https://mcp.upfirst.ai

在 Team 和 Enterprise 方案中，管理員會在組織設定下新增一次連接器，其他人只需點擊「連線」即可。

無論您如何連線，首次呼叫都會開啟 Upfirst 的登入頁面。您只需核准一次存取權限，此後連線便會與您的組織綁定。

慣例

所有工具皆遵循幾項規則。每個工具都帶有標籤，說明其對您資料的操作方式：

• 讀取 擷取資料；絕不變更任何內容。
• 寫入 建立或更新記錄。
• 刪除 永久移除記錄。此操作無法復原。

ID 來自列表工具

代理 ID 來自 list_agents，技能 ID 來自 list_agent_skills，知識 ID 來自 get_agent_knowledge，問候語 ID 來自 list_agent_greetings，自訂動作 ID 來自 list_custom_actions，通話 ID 來自 list_calls。ID 為數字字串。技能工具將 ID 作為 skillId 傳入；知識、問候語和自訂動作工具則將其作為 id 傳入。更新和刪除工具僅需該 ID，不需傳入 agentId。

記錄與代理連結

每個技能、知識條目和自訂動作都與一個或多個代理連結。建立工具接受 agentIds，這是一個至少包含一個代理 ID 的清單。將 autoLinkNewAgents 設為 true，即可將記錄同時授予您之後建立的每個代理。在這種情況下，agentIds 必須列出目前所有的代理。更新工具僅在您同時傳送 agentIds 和 autoLinkNewAgents 時才會變更連結。若兩者皆省略，則保持現有連結不變。編輯或刪除記錄會影響所有與其連結的代理。

分頁

get_agent_knowledge、list_calls 和 get_call_transcript 接受 offset 和 limit，並回傳 totalCount，因此頁面始終從相同的篩選集合中提取。其他列表工具則在一次回應中回傳所有內容。

時區

純日期（YYYY-MM-DD）會以企業的時區解讀。每週排程則以各代理自身的時區解讀，因此一個條目若連結到兩個時區的代理，會各自遵循當地時間。當您需要精確的時刻時，請傳入完整的 ISO 8601 日期時間。

刪除為永久性操作

此連線無法還原。已刪除的技能、知識條目或自訂動作會從所有與其連結的代理中消失，且這些代理會在數分鐘內停止使用該項目。

部分設定僅限儀表板操作

語音、時區和語言；技能排程；自訂動作用於驗證的 OAuth 連線；刪除轉接技能；以及匯入網站知識，皆在 Upfirst 儀表板中管理，而非透過 MCP。工具會在適用之處註明。

範例提示

Upfirst MCP 伺服器可與任何相容的 AI 客戶端搭配使用。若要開始，請將以下提示之一複製到您的客戶端，並根據您的業務進行調整。

找出您的接待員知識中的缺口

使用案例

使用此工作流程回顧過去一週的通話，找出接待員知識不足之處，以便您知道該在訓練中補充什麼。

範例提示

您正在協助找出 Upfirst 接待員的知識缺口。

回顧過去七天的通話，然後閱讀接待員目前的知識。尋找來電者提出的問題中，它無法妥善回答的部分、它缺少的資訊，以及重複出現超過一次的主題。

針對每個缺口，指出顯示該缺口的通話，並建議一條具體的知識條目來填補，並以接待員應回答的方式撰寫。將相關缺口分組，並依出現頻率排序。

不要變更任何內容。呈現缺口和建議條目以供審查。

接待員：[Name, or leave blank for all]

根據描述設定您的接待員

使用案例

使用此工作流程描述您希望接待員如何處理來電，讓您的助理建立完整設定：問候語、知識、轉接規則、排程和簡訊技能。

範例提示

您正在協助根據一段關於接待員應如何處理來電的簡述，來設定 Upfirst AI 接待員。

將描述轉化為完整設定：問候語和道別語、回答常見問題所需的知識、應轉接給真人的轉接規則、僅在特定時段適用的資訊或轉接排程，以及描述中提到的任何簡訊技能。

若描述中有任何重要事項不清楚，例如營業時間、來電應轉接給誰，或如何處理常見請求，請提出詢問，而非自行猜測。

在建立任何內容之前，先顯示完整的建議設定以供審查，然後在獲得核准後套用。

接待員應如何處理來電：[Describe your business, your hours, what callers usually need, and who calls should reach]

修正一通不理想的通話

使用案例

使用此工作流程指出一通您不滿意的通話，說明您原本的期望，並讓您的助理調整接待員的知識，使類似通話未來能處理得更好。

範例提示

您正在協助根據一通不理想的通話來改善 Upfirst 接待員。

閱讀我指出的通話，包括其文字紀錄，並比較接待員的實際做法與我原本的期望。找出導致此結果的原因：是知識中缺少了什麼、不清楚，還是與其他條目互相矛盾。

建議能讓類似通話下次處理得更好的具體變更，並以確切要新增或編輯的知識內容撰寫，同時解釋每項變更為何有幫助。

在套用變更前先顯示以供審查，然後進行已核准的編輯。

通話：[ID or a short description of the call]
我原本期望的結果：[Describe the outcome you were hoping for]

01

帳戶與代理

先熟悉環境，然後讀取或更新個別的 AI 接待員。

從這裡開始。整個帳戶的簡潔概覽：企業名稱、每位接待員及其時區、問候語、電話號碼、技能和知識，以及過去 30 天內處理的通話數。

無參數。

回傳 企業名稱 · 代理（id、名稱、時區、問候語、電話號碼、技能與知識名稱）· 過去 30 天內的通話數（僅計算已結案通話；測試和已封存通話不計入）。

列出組織的 AI 代理。使用回傳的 id 搭配下方代理範圍的工具。

無參數。

回傳 代理，每個皆包含 id 和名稱。

讀取單一代理的完整對話設定及綁定的電話號碼。

參數	類型	說明
agentId	string req	來自 list_agents 的數字代理 ID。

回傳 問候語與道別語訊息、語音語調、語速、等候音樂、時區、垃圾與免付費封鎖，以及綁定的電話號碼。

變更代理的對話設定。部分更新：僅傳送要變更的欄位；至少需提供一個可設定欄位。

參數	類型	說明
agentId	string req	要更新的代理。
greetingMessage	string opt	開場訊息。
goodbyeMessage	string opt	結束訊息。
voiceTone	enum opt	friendly · professional
speechRate	number opt	0.7 · 0.85 · 1 · 1.1 · 1.2
holdMusic	enum opt	ringTone · gentleGuitar · marimba · softKeys
isSpamCallsBlocked	boolean opt	封鎖疑似垃圾電話。
isTollFreeCallsBlocked	boolean opt	封鎖免付費電話。

語音、時區和語言在儀表板中管理，無法在此變更。兩個封鎖旗標為組織層級設定：設定任一項都會變更所有啟用中的代理，與儀表板相同。greetingMessage 為預設問候語。特定時段或日期的問候語有其專屬工具，請參閱排程問候語。

回傳 更新後的代理，格式與 get_agent_by_id 相同。

02

排程問候語

排程問候語是接待員在其排程內的通話開始時所說的內容，例如下班後或假日問候語。每個排程問候語屬於單一代理。當沒有排程問候語符合通話時間時，代理會使用其預設問候語，該問候語可透過 get_agent_by_id 讀取，並以 update_agent 變更。

列出代理的排程問候語，包括未啟用的。在變更問候語前請先閱讀此清單，以免在未察覺的情況下覆寫內容。

參數	類型	說明
agentId	string req	要列出其問候語的代理。

回傳 每個問候語的 id、text、啟用旗標、kind 和 schedule。kind 為唯讀：text 表示問候語會照原樣朗讀，instruction 表示代理會根據其內容建構問候語，unknown 表示尚未分類。

為代理新增排程問候語。僅在整個請求有效時，問候語才會被儲存。

參數	類型	說明
agentId	string req	問候語所屬的代理。
text	string req	要說出的確切文字，或如何問候的指示。
schedule	object req	問候語使用的時間，以代理的時區為準。請參閱問候語排程。
isActive	boolean opt	問候語是否從一開始就用於來電。預設為 true。

排程不得與同一代理的其他啟用中問候語重疊。每週時段和日期會分別檢查。kind 由系統設定：它會在寫入後立即讀取 unknown，並在數秒內完成分類。

回傳 新問候語的 id 及其欄位。

變更排程問候語的文字、啟用旗標或排程。部分更新：僅傳送要變更的欄位；至少需提供一個欄位。

參數	類型	說明
id	string req	來自 list_agent_greetings 的問候語 ID。
text	string opt	新的問候語文字。
isActive	boolean opt	問候語是否用於來電。
schedule	object opt	新排程。請參閱問候語排程。

新排程會完全取代已儲存的排程，因此請先讀取問候語，再傳回您希望其擁有的完整排程。重疊規則與建立時相同。文字變更會將 kind 重設為 unknown，直到再次分類為止。

回傳 更新所寫入的欄位。

永久刪除排程問候語。

參數	類型	說明
id	string req	要刪除的問候語 ID。

已刪除的問候語無法還原。在其時段內的來電將改用其他符合的問候語，若無符合者，則使用代理的預設問候語。 問候語的排程在 days 中有每週時段，並在 dates 中有可選的特定日期，全部使用代理人的時區。days 使用與 Schedules 相同的結構：全部七天，每天各有 enabled 和 workingPeriods。dates 中的每個條目都有 date 作為 YYYY-MM-DD，並在 periods 中至少包含一個時間範圍。日期條目會覆蓋該天的每週時段，這就是你設定假日問候語的方式。

{
  "days": {
    "monday":    { "enabled": true,  "workingPeriods": [{ "from": "17:00", "to": "23:59" }] },
    "tuesday":   { "enabled": true,  "workingPeriods": [{ "from": "17:00", "to": "23:59" }] },
    "wednesday": { "enabled": true,  "workingPeriods": [{ "from": "17:00", "to": "23:59" }] },
    "thursday":  { "enabled": true,  "workingPeriods": [{ "from": "17:00", "to": "23:59" }] },
    "friday":    { "enabled": true,  "workingPeriods": [{ "from": "17:00", "to": "23:59" }] },
    "saturday":  { "enabled": false, "workingPeriods": [] },
    "sunday":    { "enabled": false, "workingPeriods": [] }
  },
  "dates": [
    { "date": "2026-12-25", "periods": [{ "from": "00:00", "to": "23:59" }] }
  ]
}

03

技能

技能是接待員在通話中可以採取的行動：傳簡訊給來電者、傳送排程連結、轉接通話、預約 appointments，或呼叫外部 API。每種技能都有各自的工具，因此你傳遞的欄位永遠是該種類所使用的欄位。排程技能在此為唯讀，並在儀表板上管理。Webhook 技能的設定位於其所連結的自訂動作上；請使用下方的 Custom actions 工具來讀取和編輯。

列出為代理人設定的技能，預設包含停用的技能。

參數	類型	說明
agentId	string req	要列出技能的代理人。
llmTool	enum opt	僅列出此種類的技能：sendSms · sendScheduleSms · transferCall · scheduleSlot · customWebhook。
includeInactive	boolean opt	包含已關閉的技能。預設 true。

回傳技能：id、名稱、slug、種類、啟用旗標、儲存的設定、可選的每週排程。customWebhook 列具有空的設定和一個 webhook 區塊，包含所連結動作的 URL、HTTP 方法和時機；使用 list_custom_actions 讀取其完整設定。

排程僅在通話中對轉接技能生效。其他種類會儲存排程但忽略它。

新增一個簡訊技能：接待員可以在通話中傳送給來電者的 SMS。sendSms 會按原樣傳送訊息。sendScheduleSms 會將訊息與組織的排程連結一起傳送。

參數	類型	說明
agentIds	string[] req	獲得該技能的代理人，至少一個。來自 list_agents 的 ID。
autoLinkNewAgents	boolean opt	也將技能授予之後建立的每個代理人。當 true 時，agentIds 必須列出每個目前的代理人。預設 false。
llmTool	enum req	sendSms · sendScheduleSms
name	string req	簡短標籤，顯示在儀表板上。
message	string req	代理人傳送的 SMS 文字，最多 306 個字元。
instruction	string req	代理人在通話中應何時傳送。
isActive	boolean opt	一開始就啟用。預設 true。

訊息會通過內容過濾器，該過濾器會拒絕促銷或其他受限的措辭。

回傳新技能的 id 和你傳送的欄位（llmTool、name、message、instruction、isActive）。使用 list_agent_skills 讀取已儲存的技能。

變更簡訊技能。部分更新：只有你傳送的欄位會變更。至少傳送一個可設定的欄位或一組新的代理人。

參數	類型	說明
skillId	string req	來自 list_agent_skills 的技能 ID。
llmTool	enum opt	在 sendSms 和 sendScheduleSms 之間切換。
name	string opt	新標籤。
message	string opt	新的 SMS 文字，最多 306 個字元。
instruction	string opt	關於何時傳送的新指引。
isActive	boolean opt	開啟或關閉技能。
agentIds	string[] opt	獲得該技能的新代理人集合。與 autoLinkNewAgents 一起傳送，或兩者都省略以保留目前的連結。
autoLinkNewAgents	boolean opt	也將技能授予之後建立的每個代理人。當 true 時，agentIds 必須列出每個目前的代理人。

回傳更新所寫入的欄位。

永久刪除與其連結的每個代理人的簡訊技能。這些代理人將停止傳送該訊息。

參數	類型	說明
skillId	string req	要刪除的技能 ID。

無法恢復已刪除的技能。要取回它意味著從頭開始重新建立。

回傳 { id, note }，其中 note 以純文字確認刪除。

新增一個轉接技能：將進行中的通話轉接給某人的規則。condition 告訴代理人何時轉接，preTransferMessage 是它先對來電者說的話，而 destinations 是它依序撥打的號碼。

參數	類型	說明
agentIds	string[] req	獲得該技能的代理人，至少一個。來自 list_agents 的 ID。
autoLinkNewAgents	boolean opt	也將技能授予之後建立的每個代理人。當 true 時，agentIds 必須列出每個目前的代理人。預設 false。
name	string req	簡短標籤，顯示在儀表板上。
condition	string req	何時轉接，以純文字說明。
preTransferMessage	string req	代理人在轉接前說的話。
destinations	array req	一個或多個目標，依序嘗試，每個 { phoneNumber, label, phoneExtension }。phoneNumber 為必填，且必須是 E.164 格式（例如 +12025550123）。
ringTimeoutSeconds	number opt	每個目的地的響鈴時間，5–60。
noAnswerAction	enum opt	endCall · returnToAgent
transferMethod	enum opt	cold 直接將來電者轉接 · warm 先向目的地簡報。
transferCallerId	enum opt	目的地看到的號碼：upfirstNumber · callerNumber。
recordingMode	enum opt	agentOnly 在轉接時停止錄音 · fullCall 在轉接後繼續錄音。
isActive	boolean opt	一開始就啟用。預設 true。
schedule	object opt	技能提供的每週時段，使用代理人的時區。省略則為隨時可用。請參閱 Schedules。

每個目的地必須與所連結代理人的其中一個 Upfirst 號碼位於同一國家。省略時，技能在通話時使用儀表板的預設值：30 秒響鈴、無人接聽則結束通話、冷轉接、以 Upfirst 號碼作為來電顯示，以及錄音在轉接時停止。

回傳新技能的 id 和你傳送的欄位。使用 list_agent_skills 讀取已儲存的技能。

變更轉接技能。部分更新：只有你傳送的欄位會變更。至少傳送一個可設定的欄位或一組新的代理人。

參數	類型	說明
skillId	string req	來自 list_agent_skills 的技能 ID。
destinations	array opt	取代整個清單。傳送每個你想保留的號碼。
schedule	object opt	取代已儲存的時段。null 清除排程，使技能全天候可用。
其他建立欄位	opt	name、condition、preTransferMessage、ringTimeoutSeconds、noAnswerAction、transferMethod、transferCallerId、recordingMode、isActive。與建立時相同的值。
agentIds	string[] opt	獲得該技能的新代理人集合。與 autoLinkNewAgents 一起傳送，或兩者都省略以保留目前的連結。
autoLinkNewAgents	boolean opt	也將技能授予之後建立的每個代理人。當 true 時，agentIds 必須列出每個目前的代理人。

每個目的地必須與所連結代理人的其中一個 Upfirst 號碼位於同一國家。

技能的種類在建立時即固定。傳遞排程或 webhook 技能的 ID 會被視為找不到。

回傳更新所寫入的欄位。

沒有用於此的工具。轉接技能在 Upfirst 儀表板上刪除。透過 MCP，你可以改為將其關閉：使用 update_transfer_call_skill 設定 isActive: false，代理人將停止提供轉接，而技能仍保持設定狀態。

04

知識

接待員的知識是它回答來電者的依據。在 Upfirst 儀表板中，這些條目位於 Training 下。每個條目都是你撰寫的文字，或從網站匯入的內容。一個條目可以連結到多個代理人，編輯或刪除它會改變每個連結代理人的回答。寫入會在幾分鐘內自動重新訓練接待員。

讀取代理人的知識庫。每個條目都會完整回傳，包含完整內容，絕不會是預覽。

參數	類型	說明
agentId	string req	要讀取知識的代理人。
id	string opt	僅回傳這一個條目。
offset	number opt	要跳過的條目數。預設 0。
limit	number opt	最大條目數，1–100。預設 25。

回傳條目：id、名稱、類型（text/website）、啟用旗標、完整內容、來源 URL 和每週排程，以及 totalCount。

新增一個文字條目到一個或多個接待員的訓練中。新條目會放在每個連結代理人清單的頂部。

參數	類型	說明
agentIds	string[] req	獲得該條目的代理人，至少一個。來自 list_agents 的 ID。
autoLinkNewAgents	boolean opt	也將條目授予之後建立的每個代理人。當 true 時，agentIds 必須列出每個目前的代理人。預設 false。
name	string req	條目的顯示名稱。
content	string req	純文字，最多 250,000 個字元。
isActive	boolean opt	一開始就啟用。預設 true。
schedule	object opt	將條目限制在營業時間內。省略則為隨時啟用。請參閱 Schedules。

回傳新條目的 id、name、isActive、schedule（始終啟用時為 null）和 contentLength（以字元計）。使用 get_agent_knowledge 讀取完整條目。

變更條目的名稱、啟用旗標、內容、排程或哪些代理人可以看到它。部分更新：至少傳送一個可設定的欄位或一組新的代理人。

參數	類型	說明
id	string req	來自 get_agent_knowledge 的條目 ID。
name、isActive	opt	新名稱 / 啟用旗標。
content	string opt	新文字，完全取代已儲存的內容。最多 250,000 個字元。
schedule	object opt	新排程。null 清除它，使條目始終可用；省略則保留已儲存的排程。
agentIds	string[] opt	獲得該條目的新代理人集合。與 autoLinkNewAgents 一起傳送，或兩者都省略以保留目前的連結。
autoLinkNewAgents	boolean opt	也將條目授予之後建立的每個代理人。當 true 時，agentIds 必須列出每個目前的代理人。

內容會被取代，絕不會附加。先用 get_agent_knowledge 讀取條目，然後傳回你希望它擁有的完整文字，包括你想保留的部分。編輯會改變每個連結到該條目的代理人所說的內容。

回傳更新所寫入的欄位。新內容會以 contentLength 回傳，而不是完整文字。

永久刪除一個知識條目。

參數	類型	說明
id	string req	要刪除的條目 ID。

無法恢復已刪除的條目。刪除它會將其從每個連結的代理人中移除。

回傳 { id, note }，其中 note 以純文字確認刪除。 排程會將知識條目（或轉接技能）限制在營業時間內，並以企業的營業時區為準。這是以每週工作日為單位的物件。你傳送的每個排程都必須包含全部七天；條目不適用的那天，其 enabled: false 為空，且 workingPeriods 為空。時間採用代理時區的 24 小時制 HH:MM。

排程條目只會在對應時段內存在於接待員的知識中。時段之外，該條目就像不存在一樣，因此接待員絕不會在錯誤時間依據它回答。

這使得排程成為處理特定時間事實的可靠方式。為了讓營業與打烊時間萬無一失，請新增一個僅限於營業時間的條目，內容為「我們目前營業中」，以及另一個僅限於打烊時間的條目，內容為「我們目前休息中」。兩者永遠只會有一個生效，接待員不會搞混。

{
  "days": {
    "monday":    { "enabled": true,  "workingPeriods": [{ "from": "09:00", "to": "17:00" }] },
    "tuesday":   { "enabled": true,  "workingPeriods": [{ "from": "09:00", "to": "17:00" }] },
    "wednesday": { "enabled": true,  "workingPeriods": [{ "from": "09:00", "to": "17:00" }] },
    "thursday":  { "enabled": true,  "workingPeriods": [{ "from": "09:00", "to": "17:00" }] },
    "friday":    { "enabled": true,  "workingPeriods": [{ "from": "09:00", "to": "17:00" }] },
    "saturday":  { "enabled": false, "workingPeriods": [] },
    "sunday":    { "enabled": false, "workingPeriods": [] }
  }
}

05

自訂動作

自訂動作是接待員對外部 HTTP API 進行的呼叫。timing 決定其執行時機：before 在對話前觸發，且只能使用系統變數；during 會在通話中提供給代理，由代理根據描述決定是否呼叫；after 在通話結束後觸發，可選擇每次觸發，或是在符合自然語言條件時觸發。

變數會以 {{name}} 的形式插入 URL、查詢參數、標頭與內文中。動作會連結到一個或多個代理，編輯或刪除動作會改變所有已連結代理的行為。在 list_agent_skills 中，customWebhook 技能是自訂動作在代理端的檢視。動作可用於驗證的 OAuth 連線，是在 Upfirst 儀表板上設定的。

代理可用的每個自訂動作，皆包含其完整設定。在改寫動作前請先閱讀此內容，以免在未察覺的情況下覆寫任何項目。

參數	型別	說明
agentId	string req	要列出動作的代理。所有連結到此代理的動作都會包含在內。
id	string opt	只回傳這一個動作。

回傳 customActions，每個皆包含 id、agentIds（動作連結的所有代理）、autoLinkNewAgents、名稱、說明、時機、HTTP 方法、URL、驗證型別與 OAuth 連線 ID、失敗訊息、逾時、啟用旗標、變數、查詢參數、標頭、允許的輸出欄位、範例值、內文範本，以及事後時機條件。

名稱看起來像憑證（token、key、secret、authorization）的標頭，會以 [redacted] 回傳；真實值絕不會被讀出。已刪除的動作會被省略。

新增自訂動作，並將其連結到一個或多個代理。

參數	型別	說明
agentIds	string[] req	會取得此動作的代理，至少一個。ID 來自 list_agents。
autoLinkNewAgents	boolean opt	也將此動作提供給之後建立的每個代理。當 true 時，agentIds 必須列出目前所有代理。預設為 false。
name	string req	簡短標籤，顯示於儀表板。
description	string req	動作的用途，以自然語言描述。before 與 during 時機會將其呈現在代理面前，由代理根據此文字決定是否呼叫 API。after 時機會忽略此文字。
timing	enum req	before · during · after
httpMethod	enum req	GET · POST · PUT · PATCH · DELETE
url	string req	請求送達的端點。可包含 {{variable}} 佔位符。
authType	enum req	none 以未驗證方式傳送請求 · bearer 需要在 headers 中帶有 Authorization 標頭 · customHeaders 透過你提供的標頭進行驗證 · oauth_connection 從連線解析 token，且需要 oauthConnectionId。
fallbackMessage	string req	請求失敗或逾時時，代理告訴來電者的內容。
oauthConnectionId	string opt	已連線 OAuth 連線的數值 ID。oauth_connection 需要此欄位，其他驗證型別則拒絕此欄位。可從已使用該連線的動作之 list_custom_actions 取得。
variables	array opt	插入請求中的值，每個為 { name, description, exampleValue, isSystem, required }。name 與 description 為必填，且名稱必須唯一。系統變數由 Upfirst 從通話本身填入；自訂變數則從來電者收集。before 時機的動作只能使用系統變數。預設為 []。
queryParams	array opt	查詢字串參數，每個為 { key, value }。值可使用佔位符。預設為 []。
headers	array opt	請求標頭，每個為 { key, value }。Bearer 驗證會在此處的 Authorization 標頭中攜帶其 token。絕不要回傳 [redacted] 佔位符。預設為 []。
allowedOutputFields	string[] opt	代理可讀取的 JSON 回應欄位。空白則原封不動傳遞回應。預設為 []。
bodyTemplate	string opt	請求內文，原樣傳送並替換佔位符。空白則無內文。
sampleValues	object opt	每個變數名稱對應一個值，用於試用動作時。
timeoutSeconds	integer opt	1–30。預設為 10。
isActive	boolean opt	一開始即啟用。預設為 true。
condition	string or null opt	僅限 after 時機。以自然語言規則比對已完成的通話；null 在每次通話後觸發。before 與 during 時機請留空。

回傳已建立的動作及其新 ID。

變更自訂動作。部分更新：只有你傳送的欄位會被變更。至少傳送一個可設定欄位或一組新的代理。清單會整體替換，不會合併，因此請先使用 list_custom_actions 讀取動作。

參數	型別	說明
id	string req	來自 list_custom_actions 的動作 ID。
agentIds	string[] opt	會取得此動作的新代理集合。請與 autoLinkNewAgents 一起傳送，或兩者都留空以保留目前連結。
autoLinkNewAgents	boolean opt	也將此動作提供給之後建立的每個代理。當 true 時，agentIds 必須列出目前所有代理。
oauthConnectionId	string or null opt	null 會清除它。在將動作移離 oauth_connection 驗證型別的同一呼叫中，傳送 null。
condition	string or null opt	null 會清除它。在將動作移離 after 時機的同一呼叫中，傳送 null。
variables、queryParams、headers、allowedOutputFields	array opt	每個皆替換其整個清單。傳送每個你想保留的條目。帶有 [redacted] 佔位符的標頭會被拒絕；請傳送真實值或省略該標頭。
其他建立欄位	opt	name、description、timing、httpMethod、url、authType、bodyTemplate、sampleValues、fallbackMessage、timeoutSeconds、isActive。與建立時相同的值。

連結到多個代理的動作，會同時為所有代理編輯。

回傳更新所寫入的欄位。

永久刪除自訂動作。所有連結到它的代理都會停止呼叫該 API。

參數	型別	說明
id	string req	要刪除的動作 ID。

已刪除的動作無法還原。要恢復就必須從頭重新建立，而 list_custom_actions 只會在動作仍存在時回傳其設定。

回傳 { id, note }，其中 note 以自然語言確認刪除。

06

通話

讀取企業的通話歷史、單一通話的詳細資料及其逐字稿。只有已結束的通話會出現；通話結束後不久即會顯示。

列出並篩選通話歷史，最新的在前。精簡列，不含逐字稿或摘要（請使用下方工具取得）。

參數	型別	說明
statuses	enum[] opt	依結果篩選，每通電話恰好一個：test · blocked · spam · hungUp · completed。
query	string opt	對通話摘要與逐字稿進行自由文字搜尋。
tags	string[] opt	比對帶有任一這些標籤的通話（依名稱或 ID）。
startDate	date opt	純 YYYY-MM-DD = 企業時區的曆日，或完整的 ISO 日期時間。
endDate	date opt	同上；包含當日。
archived	boolean opt	回傳已封存通話而非作用中通話。預設為 false。
offset、limit	number opt	分頁。limit 為 1–100，預設為 25。

回傳通話列（來電者、時間、持續時間、結果、標籤、連結的聯絡人、逐字稿回合數）加上 totalCount。

單一通話的完整詳細資料，包含除逐字稿文字與錄音以外的所有內容。

參數	型別	說明
callId	string req	來自 list_calls 的數值通話 ID。

回傳時間、結果、來電者與接待員號碼、AI 撰寫的摘要、擷取的資料欄位、代理使用的技能（含各自觸發時間）、標籤、你團隊的評論，以及逐字稿回合數。

單一通話的對話文字，以有序回合呈現，每個回合標記 [mm:ss] 偏移量與發言者。

參數	型別	說明
callId	string req	來自 list_calls 的數值通話 ID。
offset、limit	number opt	回合分頁。limit 為 1–200，預設為 100。一般通話一次回應即可裝下；只有當註記顯示還有更多回合時才分頁。

發言者為 Agent（AI 接待員）、Caller（撥號者）與 Transferee（通話轉接給的人類）。

回傳回合（偏移量、發言者、文字）加上 totalCount。

常見問題

如何讓 Upfirst 開始接聽我的電話？

我們會提供你一組電話號碼。你可以直接將該號碼給出去讓別人撥打，但大多數企業會將既有號碼的來電轉接至此。

你可以選擇轉接的程度：每通都轉、只轉接漏接的來電，或視你的電話、電信商或 VoIP 系統而定，只在特定時段轉接。每個供應商的步驟都不同，請參閱 將所有來電轉接至 Upfirst 以取得對應步驟。

我需要 API 金鑰嗎？

不需要。授權採用標準的 OAuth 2.1 登入。第一次呼叫會開啟 Upfirst 的登入頁面，你核准一次存取即可，無需複製、貼上或儲存任何內容。

我可以搭配哪些 AI 助理使用？

任何支援透過 HTTP 使用遠端 MCP 伺服器的用戶端皆可。連線 一節包含 Claude、ChatGPT、Claude Code、Cursor、VS Code 與 Codex 的設定方式。其他用戶端請指向 https://mcp.upfirst.ai 作為可串流 HTTP 伺服器，它會在第一次呼叫時處理登入。

我的助理可以存取什麼？

只有你登入的組織。每個工具都限定於該組織，來自任何其他組織的 ID 永遠無法存取。在該組織內，助理可以讀取通話與逐字稿，並變更接待員設定、技能、知識與自訂動作，以及選擇每個項目適用的接待員，因此請將此連線視同登入儀表板來對待。

為什麼我剛接到的通話沒有出現？ 只有已結束的通話會顯示，且通話結束後不久便會出現。進行中的通話在掛斷前不會顯示。如果通話仍然找不到，請檢查是否已封存，因為 list_calls 只會回傳進行中的通話，除非你傳入 archived: true。

透過 MCP 有哪些事情無法做到？

語音、時區和語言；排程技能；自訂動作的 OAuth 連線；刪除轉接技能；以及從網站匯入知識，這些都需在 Upfirst 儀表板中管理。通話錄音也無法透過此連線取得。相關工具會在適用之處說明這些限制。