WordPress 客服工單系統做法 Fluent Support 與 HelpScout 串接實作指南

你的客服訊息是不是散落在表單通知、訂單備註、FB 私訊, 還有各種信箱？時間一久, 不是漏回, 就是重複回。把 WordPress 站內工單和 HelpScout 的信箱式流程接起來, 通常是中小企業把客服做穩的第一步。

這篇會用工程實作角度, 講清楚 Fluent Support HelpScout 串接 的做法與選型。你會拿到可直接照做的設定清單, 還有兩條常見串接流程的步驟與 PHP 範例。

先釐清目標, 你要「同步」還是只要「搬家」

很多人一開始就想做雙向同步, 但其實多半只需要其中一種。

如果你只是要把舊客服資料搬到 WordPress, Fluent Support 已經提供 HelpScout 匯入工具, 適合「一次性遷移」, 不用自己寫 API。可以先看官方的 HelpScout Ticket Migrator 說明, 確認是否符合你的情境。

若你要的是「持續整合」, 例如 WordPress 會員資料、訂單資訊要跟 HelpScout 對上, 那才需要做串接。這時候最重要的是決定, 你把誰當主系統：

• Fluent Support 當主系統, HelpScout 當升級的共享信箱與內部協作工具
• HelpScout 當主系統, WordPress 只負責收集資料與回寫狀態

下面這張表先幫你快速比對定位。

重點很簡單, 你要先選「單一真實來源」(source of truth), 不然雙向很容易打架。

串接前的必備設定, 以及你一定要做的對應表

在 2026 年 3 月這個時間點, HelpScout API 與 Webhooks 還在持續更新, 所以欄位與事件請以官方文件為準, 特別是事件名稱與簽章驗證方式。建議先熟一下 Help Scout Webhooks 官方總覽。

開始前, 你需要把這些資訊準備好, 少一個就會卡關：

HelpScout 端需要

• mailbox, 以及要放工單的資料夾或狀態規則
• My App 或 OAuth2 應用, 取得 App ID, App Secret, Redirect URL (若你用 OAuth flow)
• API 存取權限與 token 管理方式 (建議做可輪替)
• Webhooks App 設定, 以及事件要送到哪個 URL
• Workflows 規則, 例如自動加 tag, 自動指派給某個 team

WordPress, Fluent Support 端需要

• Fluent Support Workflows (用來觸發外送 Webhook), 官方文件在 Outgoing Webhook 設定
• 一個用來接 Webhook 的 REST API endpoint
• Fluent Support 與 WordPress 的權限策略, 例如 Application Password 或自建簽章
• 「對應表」, 把 fluent_ticket_id 對到 helpscout_conversation_id

把對應表想像成快遞的「包裹單號」。沒有它, 你就無法把 HelpScout 的回覆準確回寫到原本那張 WordPress 工單。常見做法是存到自建資料表, 或以 ticket meta 的方式存 helpscout_conversation_id。

最常見的坑是「事件重送」。不管你用 Webhook 或 iPaaS, 都要做去重, 例如用 conversation_id + event_type + timestamp 當 idempotency key。

流程示例 1, Fluent Support 新工單, 自動在 HelpScout 建立 conversation 並加 tag 指派

這條流程最常用, 因為它把 WordPress 的入口統一收斂到 HelpScout, 客服就不用守兩套介面。

做法 A, 用 Fluent Support 外送 Webhook, 接到你的 WordPress, 再呼叫 HelpScout API

1. 在 Fluent Support 建 Workflow, Trigger 選「新工單建立」
2. Action 選外送 Webhook, payload 用 JSON, 帶出 ticket id, 主旨, 內容, 客戶 email
3. Webhook URL 指到你站內的接收端, 例如 POST /wp-json/hs-bridge/v1/fluent/new-ticket
4. 接收端拿到資料後, 呼叫 HelpScout API 建 conversation, 然後加 tag, 指派人員
5. 成功後, 把 conversationId 存回該 ticket 的對應表

下面是用 wp_remote_post() 呼叫 HelpScout API 的精簡範例 (欄位依你 mailbox 與 API 規格調整)：

$token = get_option('helpscout_access_token'); // 你自己的 token 管理
$mailbox_id = 123456;


$body = [
  'subject' => $ticket_subject,
  'type'    => 'email',
  'status'  => 'active',
  'mailboxId' => $mailbox_id,
  'customer' => [
    'email' => $customer_email,
    'firstName' => $customer_name
  ],
  'threads' => [[
    'type' => 'customer',
    'text' => $ticket_message
  ]]
];


$res = wp_remote_post('https://api.helpscout.net/v2/conversations', [
  'headers' => [
    'Authorization' => 'Bearer ' . $token,
    'Content-Type'  => 'application/json'
  ],
  'body'    => wp_json_encode($body),
  'timeout' => 15
]);


// 成功後解析 conversation id, 寫入對應表, 再呼叫 tags 或 assign API (依官方文件)

若你想少寫一點膠水碼, 也可以先用 no-code 路線驗證流程, 例如 Uncanny Automator 的 Fluent Support 連 Help Scout 連接頁, 先跑通再決定要不要自建。

HelpScout 的 tag 更新有一個特性, 有些 API 需要「整包送出 tags 清單」, 少送的會被移除。實作前先在測試 mailbox 驗證行為, 再上正式環境。

流程示例 2, HelpScout 事件(回覆, 指派, 狀態)回寫到 WordPress, 更新 ticket 狀態或備註

第二條流程的核心是 Webhook。HelpScout Webhook 觸發後, 你收到的不一定是完整內容, 常見是 resource URI, 你需要再用 API 把資料抓回來。設定與 payload 規格請以官方文件為準, 你也可以參考 Create Webhook API 文件 了解必要欄位。

1) HelpScout 端建立 Webhook

• 在 HelpScout 的 Webhooks App 建立一條 webhook
• URL 指到你的 WordPress, 例如 POST /wp-json/hs-bridge/v1/helpscout/event
• events 選你要的, 常見像 convo.assigned, convo.created, convo.customer.reply.created (事件名稱依官方清單)
• 設定 secret, 讓你可以驗證來源

2) WordPress 建接收端 (REST API endpoint)並驗證簽章

add_action('rest_api_init', function () {
  register_rest_route('hs-bridge/v1', '/helpscout/event', [
    'methods'  => 'POST',
    'callback' => 'hs_bridge_receive_event',
    'permission_callback' => '__return_true'
  ]);
});


function hs_bridge_receive_event(WP_REST_Request $req) {
  $raw = $req->get_body();
  $secret = get_option('helpscout_webhook_secret');


  $sig = $req->get_header('X-HelpScout-Signature'); // header 名稱以官方為準
  // 依官方規格做 HMAC 驗證, 不通過就 return 401


  $payload = json_decode($raw, true);
  $resource_uri = $payload['_links']['resource']['href'] ?? '';


  // 用 HelpScout API 抓 conversation 詳細資料, 解析 conversationId, 狀態, 最新 thread
  // 用對應表找到 fluent_ticket_id, 然後回寫
  return new WP_REST_Response(['ok' => true], 200);
}

3) 回寫 Fluent Support (更新狀態或新增內部備註)

若你要把 HelpScout 的回覆回寫到 Fluent Support, 常見做法是呼叫 Fluent Support REST API。根據 Fluent Support 的 API 路徑慣例, 你可以用 POST /wp-json/fluent-support/v2/tickets/{id}/reply 新增一則回覆或備註 (權限與欄位以你站內實際文件為準)。

$ticket_id = 999;
$note = "HelpScout 回覆已收到, conversation: " . $conversation_id;


$res = wp_remote_post(home_url("/wp-json/fluent-support/v2/tickets/{$ticket_id}/reply"), [
  'headers' => [
    'Content-Type' => 'application/json',
    'Authorization' => 'Basic ' . base64_encode($wp_user . ':' . $app_password)
  ],
  'body' => wp_json_encode([
    'message' => $note
  ]),
  'timeout' => 15
]);

如果你更在意穩定, 可以先「只回寫狀態」到 WordPress 自訂欄位, 讓客服在站內看得到同步結果, 等流程跑順再把回覆內容也同步。

串接方案怎麼選, 以及上線前檢查清單

下面這張表用成本, 難度, 可維護性來比對三種路線, 你可以照團隊技術量能挑。

想看 iPaaS 類型的整合範例, 可參考 Zoho Flow 的 Fluent Support x Help Scout 整合頁, 先理解它們通常怎麼定義 trigger 與 action。

最後給一份上線前檢查清單, 建議你照順序勾完再切正式流量：

• Webhook 驗證與白名單, 至少做到 secret 或簽章驗證
• 失敗重試策略, 以及去重機制(避免重複建 conversation)
• 日誌與告警, 例如每小時統計失敗筆數
• 對應表備份, 以及可重建策略
• 測試 mailbox 與 staging 站先跑一輪, 再上正式

結語

把 WordPress 的 Fluent Support 接到 HelpScout, 本質上是在做一條「可追蹤的資料管線」。當你把對應表, 去重, 驗證做好, 客服就不會再被系統追著跑。接下來你可以再把訂單, 會員等資料一併帶入, 讓回覆更快更準。若你希望在不打亂現有營運的前提下導入, 也可以把需求整理成流程圖, 讓工程一次做對, 把 串接 變成可維護的日常。