🏪線上下通路交談

此 API 為 2025-09-15 後版本 v.2.93.05 開放。

此 API 用於在系統中建立一筆新的「交談內容（text call）」記錄，通常由外部入口（例如官網 Web Form、線上互動表單、或第三方服務）觸發。 開發者可透過此端點，將使用者輸入的文字訊息寫入系統，並依需求指定或關聯到既有的 contact／onsite_contact。若未指定或指定的對象不存在，系統會依規則自動建立並完成掛載。

相關名詞

名稱	說明	系統欄位 / 範例	使用情境
contact_id	系統中的「客戶」識別系統編號。	contact_id = 1001	當你已經知道客戶編號，並希望將訊息直接掛到該客戶底下。
onsite_contact	線上／下通路的聯絡人。它是中介層，代表該客戶在某個 Onsite 帳號下的身份。	—	用來區隔不同通路的對話，例如同一個客戶在官網表單、門市、App 的互動。
onsite_contact_id	onsite_contact 的系統識別編號。系統會自動產生唯一 ID。	onsite_contact_id = 501	當你已經知道目標 onsite_contact，可以直接傳此 ID 來掛載訊息。
onsite_contact_sn	onsite_contact 的獨立識別欄位（序號）。通常可存放「會員編號」或其他唯一字串，由呼叫方自行決定與維護。	onsite_contact_sn = "VIP-A0001"	如果想用外部系統的會員編號或識別碼作為查找依據，就把它存到 sn，之後傳這個值系統就能比對。
message	本次要寫入的訊息內容。	"想詢問商品庫存"	實際的交談文字，來源可能是 Web Form、線上表單或其他輸入。
onsite_account	線上通路管道，一個帳號代表一個「通路來源」。你可以依地區或網站版本建立不同帳號，例如「台灣官網」、「日本官網」。	onsite_account_id=1	當同一個品牌有多個官網或通路，需要分別追蹤訊息來源。

---

API

curl -X POST "api/onsite-account/{onsite_account}/text-call" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <token>"

Response

回傳為 JSON 格式，

• HTTP status = 200 → 表示建立成功

• HTTP status = 422 → 驗證錯誤

• 其他 → 請依錯誤碼處理

URL Parameters

Parameter	Description
onsite_account	必填，目標線上下通路 帳號唯一識別 (string | int)

Request Body

Content-Type: application/json

欄位名稱	型別	規則 / 條件	說明
identifier_type	string	contact_id / onsite_contact_id / onsite_contact_sn / null	指定識別方式；若為 null，系統自動處理。
identifier	int/string/null	依 identifier_type 而定	對應的實際值，例如 contact_id=1001；若為 null，系統自動建立。
message	string	必填，長度 1–5000	訊息內容。
should_enter_queue	boolean	nullable；true/false	若為 true → 交談狀態將直接轉為轉接真佇列等待。
assignee_id	integer	nullable；必須存在於 employees.id	指定處理的客服/員工 ID。若未填 → 系統依 queue 或 routing 規則處理。

---

業務規則

1. 目標對象如何決定

   • 如果你在 request 裡有帶 identifier_type + identifier → 就會按照你給的方式去找對象。

   • 如果你沒有帶 → 系統會自動幫你建立一個 onsite_contact，然後把這筆訊息掛在這個對象底下。

2. 找不到對象時會怎麼辦

   • onsite_contact_sn：假設你傳入的 SN（序號）在系統裡沒有 → 系統會新建一個 onsite_contact，並把這個 SN 記起來。

   • contact_id：如果有這個會員（contact），但該客戶還沒有 onsite_contact → 系統會自動幫他建立一個，再掛上訊息。若這個 contact_id 根本不存在則會被拒絕處理。

   • onsite_contact_id：如果你指定的 ID 在系統找不到則會被拒絕處理。

3. 訊息處理

   • 不管怎樣，每次呼叫 API 都會確實新增一筆訊息，並且一定會和某個 onsite_contact 關聯。

4. should_enter_queue = false 或 null

   • 僅建立一筆交談紀錄，不觸發即時客服分派，而需要自行接應。

模擬情境

假設有一位客戶，他在你們的官網 Web Form 留了訊息，並且你知道他的會員編號，並透過 contact 客戶API 取的其系統中編號為 1001，故（contact_id = 1001）：

• 呼叫 API

  {
    "identifier_type": "contact_id",
    "identifier": 1001,
    "message": "顧客想詢問商品庫存，聯絡方式為 [email protected]"
  }

• 系統處理邏輯

  1. 先檢查 contact_id = 1001 是否存在。

  2. 如果該會員還沒有對應的 onsite_contact，系統會自動新建一個，並把這筆訊息掛進去。

  3. 最後得到一筆「訊息紀錄」，並與這位會員的 onsite_contact 綁定。

---

Example

1) 不指定對象

{
  "message": "Hello"
}

2) 指定 onsite_contact_sn

{
  "identifier_type": "onsite_contact_sn",
  "identifier": "A0001",
  "message": "Hello"
}

3) 指定 contact_id

{
  "identifier_type": "contact_id",
  "identifier": 1,
  "message": "Hello"
}

4) 指定 onsite_contact_id

{
  "identifier_type": "onsite_contact_id",
  "identifier": 1,
  "message": "Hello"
}

開發最佳實踐

在 API 開發的落地實務上，應優先考慮如何避免重複資料與額外人工作業，確保專員能以最短路徑完成客戶回覆。

第一種情境，若系統內尚無該客戶紀錄，建議透過客戶 API 先行建立客戶，再立即新增其電子郵件或電話聯絡資料，這樣可讓專員在接應交談後直接回覆客戶，而不需再回頭補充或修正資料。

第二種情境，若系統內已存在該客戶資料，則應透過 API 查詢並關聯到既有客戶，再建立新的交談紀錄，而非重複新增相同的客戶。這樣的設計不僅能維持資料完整性，減少重複紀錄造成的資訊負擔，同時也能提升專員的操作效率與使用體驗。

先呼叫 Contact API 查找可能客戶
    ├── 有存在
    │       └── 直接帶入 api/onsite-account API 建立交談
    │
    └── 沒有存在
            └── 呼叫 Contact API 建立新客戶
                    └── 新增聯絡方式 (Email / Phone)
                            └── 再帶入 api/onsite-account API 建立交談