任務（Task）

簡介

任務（Task） 是 Agent 的主動訊息能力：由 Agent 主動向用戶發起對話，而不是等待用戶先開口。

與一般對話不同，一般對話是「用戶提問 → Agent 回答」，而任務則是「平台依照您設定的條件，代替用戶向 Agent 發出一則訊息 → Agent 產生回覆 → 回覆推送給用戶」。您在任務中填寫的「觸發訊息」，本質上是代替用戶傳送給 Agent 的一句話，Agent 會像收到真實用戶訊息一樣產生回覆，最終用戶看到的是 Agent 的回覆，而不是觸發訊息本身。

典型使用情境：

前置條件

• 任務只會傳送給已經與 Agent 產生過對話的用戶。平台會為每位用戶找到其在目標管道上「最後一次活躍」的對話，並在該對話中注入訊息。沒有對話記錄的用戶不會收到任務訊息（執行明細中記為 NO_CONVERSATION）。
• 若目標管道為第三方整合（如 WhatsApp、Telegram、LINE 等），請確保對應的整合已在「Integrations」中正確設定並處於啟用狀態；整合被關閉或憑證失效會導致傳送失敗（CHANNEL_CONFIG_INVALID / CHANNEL_AUTH_FAILED）。
• 任務執行會呼叫 Agent 的 LLM 產生回覆，會正常消耗積分（Credits）。

入口

進入 開發空間 → 代理 → 選擇某個 Agent → 左側選單「Tasks」。

任務列表支援：依任務名稱搜尋、依狀態（Status）、觸發類型（Trigger）、目標用戶（Target）篩選。列表欄位說明：

建立任務

點擊右上角 New task，在右側抽屜中完成設定。

1. 基本資訊

注意：選擇 All users 時會跳出二次確認，因為這代表向該 Agent 所有管道上的全部用戶廣播。請務必確認目標對話範圍設定合理，避免誤發。

支援的目標管道

提示：部分管道因平台協定限制暫不支援伺服器端主動推送（如 Discord、DingTalk、SoBot），在管道下拉選單中會反灰並提示原因。自有管道（Web / Widget 等）的回覆會直接寫入對話，用戶下次開啟對話視窗即可看到；IM 管道與客服平台則會透過對應平台的 API 主動推送給用戶。

2. 觸發方式（Trigger）

觸發方式決定「什麼時候發」，共有三種：

主動 - 定時觸發（Active - Scheduled）

由平台依設定的時間表主動發起，適合定期播報、單次通知。

時間依任務所選的時區計算。定時任務建立後狀態為 WAITING，到達首次執行時間後進入 RUNNING；Once 任務執行完成後自動轉為 COMPLETED。

主動 - 事件觸發（Active - Event）

由您的業務系統透過 Webhook 呼叫平台來觸發，適合與訂單、付款、工單等業務事件連動。

建立任務時選擇驗證方式並填寫憑證，平台會自動產生一個唯一的 Webhook URL（建立後可在任務詳情中檢視）：

Webhook 呼叫範例

Webhook URL 形如 {平台網域}/bot/proactive-task/webhook/{webhookPath}，請以任務詳情中顯示的完整網址為準。

                      
                      POST {Webhook URL}
Content-Type: application/json
Authorization: Basic base64(username:password)

{
  "idempotency_key": "order-20260903-0001",
  "target": {
    "channel": "TELEGRAM",
    "user_id": "customer_123"
  },
  "variables": {
    "order_no": "SO-20260903-0001",
    "eta": "9月5日"
  }
}

                    

注意：Webhook 請求成功僅代表「已接收並進入傳送佇列」，實際傳送結果請在執行歷史中檢視。驗證失敗、任務已停止、目標管道不在任務的目標管道範圍內等情況都會回傳權限錯誤。單一 Webhook 網址限流 120 次 / 分鐘。

被動 - 用戶觸發（Passive - User Triggered）

由平台每分鐘掃描一次所有目標用戶，符合規則的用戶即觸發傳送，適合沉默用戶喚醒、高價值用戶關懷等情境。

規則設定

點擊 Add rule 新增規則，多條規則之間可選擇 AND（全部滿足）或 OR（任一滿足）。

說明：用戶屬性取自「變數管理 → 用戶屬性」，依用戶逐一取值（用戶未設定時取屬性預設值），適合依用戶輪廓篩選；自訂屬性取自「變數管理 → 自訂變數」，是 Agent 層級的統一值，對所有用戶相同，適合作為「總開關」類條件。所有規則欄位都是基於該用戶在目標管道上最後活躍的那則對話取值。

訊息頻率控制（Message Frequency）

被動觸發任務必須設定頻率控制：在設定的時間窗內（N 小時 / N 天），同一位用戶最多只會被該任務觸發一次，避免持續符合規則的用戶被反覆打擾。

提示：用戶最後對話時間（User's last chat time）是「過去」的時間，請使用「已過去 N 單位」類運算子；「距今 N 單位之後」類運算子只適用於未來時間欄位（如訂閱到期時間），用在最後對話時間上永遠不會命中。

3. 觸發訊息（Message）

填寫要「代替用戶」傳送給 Agent 的訊息內容。Agent 會根據這則訊息以及自身的提示詞、知識庫等產生回覆，再推送給用戶。

支援使用 {{變數}} 引用以下變數：

範例

• 定時播報：請用簡短友善的語氣，為我總結今天的產業要聞。
• 沉默喚醒：我已經幾天沒有來了，請主動問候我，並告訴我最近有什麼新功能。
• 事件通知：我的訂單 {{event.variables.order_no}} 已出貨，預計 {{event.variables.eta}} 送達，請告訴我物流資訊並提醒我注意查收。

提示：觸發訊息是寫給 Agent 看的「用戶視角」提問，而不是直接顯示給用戶的文案。如果希望 Agent 盡量原樣轉述，可以在訊息中明確要求，例如「請原樣告訴用戶：……」。

確認無誤後點擊 Create。

注意：每個 Agent 同時處於 WAITING / RUNNING 狀態的任務最多 10 個，超出後需先停止或等待既有任務完成。

任務狀態

檢視任務與執行歷史

點擊列表中的 View 進入任務詳情，包含兩個分頁：

• Configuration：任務設定的唯讀檢視。事件觸發任務可在此檢視 Webhook URL 與驗證資訊。
• Execution History：每次執行的記錄，含執行時間、目標數、成功 / 失敗數與成功率。

點擊某次執行可檢視執行明細：各管道的成功 / 失敗統計，以及逐筆傳送記錄。失敗原因說明：

停止與刪除

• Stop：處於 WAITING / RUNNING / ERROR 狀態的任務可隨時停止，停止後轉為 TERMINATED，無法恢復。
• Delete：僅 COMPLETED / TERMINATED 狀態的任務可刪除，刪除時會同步清除執行歷史與明細。

常見問題

Q：為什麼任務執行成功，但用戶看到的內容不是我填寫的觸發訊息？
觸發訊息是「代替用戶傳送給 Agent 的提問」，用戶看到的是 Agent 針對這句話產生的回覆。如需精確控制文案，請在觸發訊息中明確要求 Agent 原樣輸出。

Q：新用戶會收到任務訊息嗎？
不會。任務只會向已有對話記錄的用戶傳送，且對話建立時間需落在「目標對話範圍」內。

Q：定時任務為什麼沒有在整點準時傳送？
排程器每分鐘掃描一次，且大量傳送會依專案層級的速率限制分批推送，因此實際送達時間可能略有延後。

Q：Webhook 回傳權限錯誤（Permission deny）？
請依序檢查：Webhook URL 是否正確、驗證憑證是否相符、任務是否已被停止、請求中的 target.channel 是否屬於任務設定的目標管道。