用 OpenAPI 規格 產生串接用戶端。公開 API、工作台和 MCP 管理端點操作的是同一套工作區資源和權限。
| 能力 | 端點 |
|---|---|
| 可重複使用的工具 | GET / POST /api/v1/voice/tools |
| 讀取 / 更新 / 刪除工具 | GET / PATCH / DELETE /api/v1/voice/tools/{id} |
| 預覽或測試工具 | POST /api/v1/voice/tools/{id}/test |
| 把工具綁定到 Agent | PUT /api/v1/voice/agents/{id}/tools |
| 知識庫 | GET / POST /api/v1/voice/knowledge-bases |
| 讀取 / 更新 / 刪除知識庫 | GET / PATCH / DELETE /api/v1/voice/knowledge-bases/{id} |
| 新增 / 列出文件 | POST / GET /api/v1/voice/knowledge-bases/{id}/documents |
| 讀取 / 刪除文件 | GET / DELETE /api/v1/voice/knowledge-bases/{id}/documents/{doc_id} |
| 通話事件訂閱 | GET / POST /api/v1/voice/webhooks |
| 讀取 / 更新 / 刪除訂閱 | GET / PATCH / DELETE /api/v1/voice/webhooks/{id} |
| 傳送有簽章的測試事件 | POST /api/v1/voice/webhooks/{id}/test |
| 探索遠端 MCP 工具 | POST /api/v1/voice/mcp/discover |
| MCP 管理端點 | /api/v1/voice/mcp |
註冊一個查詢你 CRM 轉接層的 HTTP 工具：
{
"name": "lookup_customer",
"description": "Find a customer after confirming their customer ID.",
"kind": "http",
"url": "https://crm.example.com/customers/{{customer_id}}",
"method": "GET",
"read_only": true,
"credential_ref": "crm",
"input_schema": {
"type": "object",
"properties": { "customer_id": { "type": "string" } },
"required": ["customer_id"],
"additionalProperties": false
},
"response_path": "data"
}
POST /tools 傳回 { "data": { "id": "TOOL_ID", ... } }。用 PUT /agents/AGENT_ID/tools 和 { "tool_ids": ["TOOL_ID"] } 把它的定義綁定到 Agent。這會以快照取代整份工具清單；工具庫裡的工具變更後請重新綁定。刪除工具庫定義不影響已有的快照。也可以用 Agent API 的 tools 欄位讀取和取代內嵌定義。分析和掛件用 Agent API 的 analysis_config 和 widget_config 設定。
工具可以用 GET、POST、PUT、PATCH 或 DELETE。query 和 request_body 接受巢狀 JSON 範本，例如 { "customer": { "id": "{{customer_id}}" } }。整個值都是佔位符時保留原本的 JSON 型別。URL 佔位符會被編碼，而且只能出現在固定的公開 HTTPS 主機之後。沒有 request_body 時，非 GET 的工具會收到 { "arguments": {...}, "call": { "callId": "...", "agentId": "...", "toolCallId": "...", "idempotencyKey": "..." } }。response_path 用點號路徑選取欄位。簡單的 parameters 仍然接受；input_schema 另外支援巢狀物件、陣列、列舉和數值範圍。不接受外部 schema 參照和正規表示式。
static_args：不論模型寫什麼都每次帶上的值，例如門市編號；也會填入網址和請求內容裡的 {{name}}。extract：[{name, path}] 保留函式結果中的欄位（data.id），供後續函式的 {{name}} 使用，查詢得到的 customer_id 就能直接帶進接下來的下單，不用模型再說一次。開場查詢的欄位也以同樣方式保留。reject_when：最多 5 條規則 {on: caller|agent, pattern, negate}；最後一句話全部符合時不執行函式，Agent 收到 reject_message。model_says：每次呼叫時由模型寫一句話，在函式執行期間說出，取代固定的 speak_before。在 整合 → Webhook 與通知 → 連接的應用程式 連接應用程式，再到 Agent 的知識庫與工具分頁使用「加入現成函式」；不需要你自己的端點：
check_availability（某天的空閒時段）和 book_appointment（預約來電者選的時間）。Google 日曆的時段依你設定的時區、營業日、營業時間和預約長度；Cal.com 使用活動類型本身的可預約時段，來電者沒給電子郵件時使用你設定的備用信箱。save_to_sheet，依你列出的欄位新增一列，再加上通話 ID 和時間。notify_team，把 Agent 寫的訊息發到 Slack 頻道（Incoming Webhook）。這些函式由 EvaSay 控制平面以你連接的帳號執行；Worker 和 Agent 定義都不持有應用程式的憑證。透過 API 讀取 Agent 時，它們顯示為 kind: "app"（帶 app、action、connection_id、app_config）；取代 tools 時原樣傳回即可保留。應用程式只能在工作台連接。
在 Agent 的某個工具上設定 run_at_start: true，每通電話開始時、Agent 打招呼或回答之前就會呼叫它。名為 caller_number、called_number、direction、channel 或 call_id 的參數會自動帶入。回傳的欄位會填入 first_message、system_prompt 和 idle_messages 裡的 {{variables}}（下一層的欄位寫成 {{customer.name}}），完整結果也會作為背景交給 Agent。開場白有變數時最多等 3 秒；查不到的留空。每個 Agent 只能有一個工具在開場時執行。
憑證依你的工作區和目的地設定在伺服器環境中；請寫信到 support@evasay.com 申請 credential_ref。不要把 API 金鑰放進 Agent 定義、標頭、提示詞或工具參數。CRM 憑證可以放在你轉接層自己的環境裡。
向業務系統發出請求前，先預覽工具：
{
"arguments": { "customer_id": "customer-123" },
"dry_run": true,
"mock_result": { "name": "Alex", "order_status": "shipped" }
}
預覽會驗證參數並顯示對應後的請求；不會執行對話，也不會連線業務系統。設定 dry_run=false 才會真正執行。真正的寫入測試還需要 confirmed=true 和 idempotency_key（8–128 個英數字、點、底線、冒號或連字號）。測試回應包含 ok、status、duration_ms 和有長度限制的結果，不會傳回憑證。讀取和寫入測試都需要工作區的寫入權限。
通話中，業務請求會帶穩定的 Idempotency-Key，你的業務端點必須遵守它。同一通電話中相同的寫入會被去重，包括逾時後結果未知的操作。若要刻意做另一個操作，需要不同的業務參數，例如 operation_id。EvaSay 不會自動重播寫入。工具執行事件包含狀態和耗時；對話測試功能仍是文字模擬，不是工具執行測試。
POST /mcp/discover 接受 { "url": "https://crm.example.com/mcp", "credential_ref": "crm" }，傳回伺服器的工具和 schema。只註冊選定的工具：
{
"name": "lookup_customer",
"description": "Find a CRM customer by confirmed ID.",
"kind": "mcp",
"url": "https://crm.example.com/mcp",
"mcp_tool": "get_customer",
"credential_ref": "crm",
"read_only": true,
"input_schema": {
"type": "object",
"properties": { "customer_id": { "type": "string" } },
"required": ["customer_id"]
}
}
只有註冊過的工具 Agent 才能使用。遠端連線支援以 JSON 或 SSE 回應請求的 Streamable HTTP、公開 HTTPS 目的地和預先設定的憑證。不支援舊版 SSE 端點、OAuth 協商、伺服器發起的 sampling/elicitation 和二進位附件。探索不會自動授權存取伺服器的所有工具。遠端工具的 schema 必須是內嵌的，並使用支援的 JSON Schema 子集。