Telegram SCRM 與 HubSpot 整合指南：Webhook 線索同步與欄位對應最佳實踐

當你的團隊使用 Telegram Bot 承接客服與銷售線索時，一個常見瓶頸是：線索資料如何自動流入 CRM？ 手動複製使用者資訊到 HubSpot，不僅耗時，還容易遺漏關鍵欄位（如首次對話時間、使用者標籤），導致後續跟進斷層。

本文將基於實際可落地的整合模式，講解如何透過 Webhook 與 API，將 Telegram SCRM（以 TG-Staff 為例）與 HubSpot 打通。無論你是從零搭建，還是已有歷史資料需要清洗，都能找到對應的操作路徑。

---

為什麼需要將 Telegram SCRM 與 HubSpot 整合？

在 B2B 客服場景中，Telegram 使用者首次諮詢往往意味著潛在商機。如果客服只在 Telegram 介面回覆，而線索資訊停留在聊天記錄裡，銷售團隊就無法在 HubSpot 中看到完整的客戶旅程。

整合帶來的核心價值：

• 自動線索產生：使用者傳送第一條訊息，HubSpot 自動建立聯絡人記錄，無需人工輸入。
• 統一客戶檢視：Telegram 對話標籤、備註、對話摘要與 HubSpot 中的公司、交易階段關聯。
• 縮短回應到成交的週期：銷售在 CRM 中看到線索來源為「Telegram SCRM」，可直接檢視歷史對話摘要，快速判斷優先級。

TG-Staff 作為面向 Telegram Bot 的客服與營運 SaaS 平台，提供了 Webhook 推送與 API 回呼能力，是打通 Telegram 與 HubSpot 的理想中間層。

---

整合前的準備工作：帳號與權限梳理

在開始配置前，請確認以下兩項先決條件，避免操作中途因權限不足而中斷。

確認 HubSpot 帳號權限與 API 存取

• 你需要一個 HubSpot 帳號，且擁有 Super Admin 或 App Marketplace 管理員 權限。
• 推薦使用 Private App 方式取得 API Key（Access Token），因為它的權限範圍可精確控制，且不會因 OAuth 重新整理而失效。
• 在 HubSpot 後台進入 設定 → 整合 → Private Apps，建立新應用，勾選 crm.objects.contacts.write 和 crm.objects.contacts.read 權限。

確認 Telegram SCRM 平台的 Webhook 與 API 支援

以 TG-Staff 為例，它的可視化流程編輯器內建了 Webhook 傳送節點，支援在使用者觸發特定事件（如首次對話、完成選單步驟、提交表單）時，向指定 URL 傳送 JSON 格式的使用者資料。

你需要在 TG-Staff 控制台中找到 Webhook 配置 入口（路徑：專案設定 → 整合 → Webhook），或直接在流程編輯器中新增節點。如果使用其他 Telegram SCRM 平台，請確認其是否支援自訂 Webhook 和 API 回呼。

---

模式一：單向 Webhook 推送——從 Telegram 會話自動建立 HubSpot 線索

這是最快速、低風險的整合起點。適合只需要將 Telegram 使用者資訊同步到 HubSpot，不需要雙向更新的團隊。

配置 TG-Staff Webhook 觸發器

1. 在 TG-Staff 控制台打開你的 Bot 專案，進入 可視化流程編輯器。
2. 在「新使用者首次對話」或「使用者點選選單按鈕」等節點後，新增一個 Webhook 傳送 節點。
3. 設定目標 URL：https://api.hubapi.com/crm/v3/objects/contacts（HubSpot Contacts API 端點）。
4. 在請求頭中新增：
   • Authorization: Bearer <你的 HubSpot Private App Access Token>
   • Content-Type: application/json
5. 在請求體中，使用 TG-Staff 提供的變數對應使用者資料。例如：

{
  "properties": {
    "firstname": "`{{user.first_name}}`",
    "lastname": "`{{user.last_name}}`",
    "telegram_id": "`{{user.id}}`",
    "hs_lead_status": "NEW",
    "original_source": "Telegram SCRM"
  }
}

6. 選擇觸發事件為「新使用者首次對話」，並儲存流程。

HubSpot 端接收與欄位對應

HubSpot 本身不要求額外配置 Webhook 接收端（因為你是主動呼叫它的 API），但你需要在 HubSpot 中建立對應的自訂欄位來儲存 Telegram 專用資料。

TG-Staff 欄位	HubSpot 標準/自訂欄位	說明
user.first_name	firstname	HubSpot 標準姓名欄位
user.id	telegram_id (自訂)	作為唯一識別，避免重複
user.username	hs_lead_username (自訂)	方便客服識別
message.text (首條訊息)	first_conversation_message (自訂)	記錄首次諮詢內容
來源標記	original_source	設為固定值 Telegram SCRM

欄位對應注意事項：telegram_id 建議設定為 HubSpot 的 唯一識別欄位，這樣當同一個使用者重複諮詢時，API 會自動更新已有記錄而不是建立重複線索（需使用 Upsert 策略，見後文）。

---

模式二：雙向同步——實現客服操作與 CRM 資料即時連動

當團隊需要更緊密的資料協同——比如客服在 TG-Staff 中給使用者打上「高意向」標籤，這個標籤自動同步到 HubSpot；或者銷售在 HubSpot 中將線索階段改為「已成交」，客服介面立刻顯示該使用者狀態變更——你需要雙向 Webhook 架構。

實現雙向同步的步驟：

1. TG-Staff 側：在流程編輯器中，為「標籤變更」、「備註更新」、「狀態切換」等事件各添加一個 Webhook 節點，推送變更資料到 HubSpot。
2. HubSpot 側：在 HubSpot Private App 中啟用 Webhook 訂閱，訂閱 contact.propertyChange 事件。當 HubSpot 中聯絡人的某個欄位（如 hs_lead_status）變更時，HubSpot 會向 TG-Staff 的 Webhook 接收 URL 發送通知。
3. TG-Staff 側接收：TG-Staff 支援自訂 API 回呼。你需要在 TG-Staff 的「Webhook 接收」設定中，配置一個端點來接收 HubSpot 推送的變更資料，並更新本地使用者畫像。

適用場景：中大型客服團隊，需要銷售與客服共享即時客戶狀態。如果團隊規模較小或資料敏感度不高，模式一通常已足夠。

---

模式三：批量潛在客戶匯入與歷史資料清理

如果你已經有一個 Telegram 使用者群，並且之前沒有整合 CRM，那麼你需要將 TG-Staff 中的歷史使用者資料（標籤、對話次數、最後活躍時間）批量匯入 HubSpot。

兩種匯入方式對比：

方式	優點	缺點	推薦場景
CSV 匯出 + 手動匯入	操作簡單，無需開發	無法保留自訂欄位（如 telegram_id），且資料格式需手動調整	資料量 < 500 筆，臨時性一次性匯入
API 批量 Upsert	支援所有自訂欄位，可自動去重，可保留標籤關係	需要撰寫腳本或使用 Postman	資料量 > 500 筆，或需要定期增量同步

推薦做法：

1. 在 TG-Staff 專業版（支援使用者畫像匯出）中，匯出使用者列表為 JSON 或 CSV。
2. 編寫一個簡單的 Python 或 Node.js 腳本，讀取每筆記錄，呼叫 HubSpot Contacts API 的 /crm/v3/objects/contacts 端點，使用 idProperty 參數進行 Upsert（例如：idProperty=telegram_id）。
3. 腳本中注意欄位對應，尤其是將 TG-Staff 中的標籤（可能為多標籤字串）拆分為 HubSpot 的 hs_lead_group 或自訂欄位。

---

常見欄位映射策略與避坑指南

必選欄位與可選欄位劃分

欄位	必選/可選	映射建議
telegram_id	必選	映射為 HubSpot 自訂唯一識別碼，避免重複線索
first_name / last_name	可選	映射為標準 firstname / lastname
标签	可選	可映射為 HubSpot 的 hs_lead_group 或自訂分組欄位
首次对话时间	可選	映射為 first_conversation_date 自訂欄位，便於分析線索時效性
对话摘要	可選	映射為 notes 或 hs_lead_notes，供銷售快速了解背景

處理多語言與自動翻譯場景

如果啟用了 TG-Staff 的自動翻譯功能，原始使用者訊息和翻譯後內容會同時存在。建議：

• 將 原始语言代码 映射為 original_language 欄位。
• 將 翻译后内容 映射為 translated_conversation_summary 欄位。
• HubSpot 中可據此欄位判斷是否需要安排對應語種的銷售跟進。

避免資料衝突的更新策略

• 使用 Upsert 而非 Create：在 HubSpot API 請求中，添加 idProperty=telegram_id 參數。這樣當同一個使用者再次發送訊息時，API 會自動更新已有聯絡人，而不是建立新記錄。
• 設定欄位優先級：如果 HubSpot 中的某個欄位（如 company）已有值，而 TG-Staff 推送的值為空，建議在腳本中判斷：僅當 HubSpot 端欄位為空時才覆蓋，否則保留既有值。

---

整合後的驗證與常見問題排查

驗證清單：

1. 在 Telegram 中向你的 Bot 發送一條訊息。
2. 登入 HubSpot，進入聯絡人列表，查看是否自動建立了一筆新紀錄。
3. 檢查新紀錄的 telegram_id 欄位是否正確，original_source 是否為 Telegram SCRM。
4. 如果啟用了雙向同步，在 TG-Staff 中修改使用者標籤，回到 HubSpot 查看該聯絡人的標籤是否同步更新。

常見問題：

Q：使用者發送訊息後，HubSpot 沒有建立聯絡人。 A：首先檢查 TG-Staff Webhook 節點的目標 URL 是否正確（注意區分 https 和 http）。然後檢查 HubSpot API Token 是否過期或權限不足（需要在 Private App 中勾選 crm.objects.contacts.write）。最後查看 TG-Staff 的 Webhook 除錯日誌，看請求是否成功發出（HTTP 狀態碼 201 為成功）。

Q：Webhook 推送成功，但 HubSpot 欄位為空。 A：檢查請求體中的屬性名稱是否與 HubSpot 中的欄位名稱完全一致（區分大小寫）。如果使用了自訂欄位，請確保已在 HubSpot 中建立該欄位，並且欄位類型匹配（字串、數字、日期等）。

Q：雙向同步出現循環觸發。 A：檢查是否已加入版本號判斷邏輯（如 sync_version）。如果沒有，先暫停其中一個方向的 Webhook，加入版本號後再恢復。最簡單的方法：僅讓 TG-Staff 單向推送至 HubSpot，HubSpot 側不配置回呼，避免循環。

---

總結與下一步行動

本文介紹了三種 Telegram SCRM 與 HubSpot 的整合模式：

模式	適用團隊	複雜度	主要價值
單向 Webhook 推送	小型團隊，首次整合	低	快速實現線索自動建立
雙向同步	中大型團隊，需即時協同	中	客服與銷售資料即時連動
批次匯入	有歷史資料的團隊	中	完成 CRM 資料初始化

整合完成後，建議持續關注的指標：線索轉換率（從 Telegram 使用者到 HubSpot 線索的佔比）、客服回應時間（是否因整合而縮短）、CRM 欄位完整率（是否所有重要欄位都已填寫）。

下一步行動：

• 立即註冊 TG-Staff 免費試用（3 天），體驗 Webhook 配置與使用者畫像功能。
• 查閱 TG-Staff 官方文件 取得 Webhook 除錯日誌與 API 參考。
• 配置過程中遇到問題，可聯絡 @tgstaff_robot 取得即時支援。

打通 Telegram 客服與 HubSpot CRM 的資料流，是提升 B2B 線索管理效率的關鍵一步。從最簡單的單向推送開始，逐步迭代到雙向同步，讓你的客戶資料始終處於最新狀態。