ContactLoop

內部上手指南 · 請先登入

沒有密碼?請向管理員索取。

總覽

從零認識 ContactLoop

這份指南把新人從「不知道 ContactLoop 是什麼」一路帶到「能在 stg 環境建一個帳號、跑出一套測試」。內容來自實際 repo(samurai-world、ava、auto_cl)的程式碼與內部文件,不是憑空想像。

2 個核心系統 3 個環境 40+ 個頁面 2 條上手路線

兩大系統各做什麼

ContactLoop 由兩個互相呼叫的系統組成,合起來才是一個完整的「名單 → 觸發 → 對話 → 回寫」迴圈(Contact Loop 由此得名)。

Samurai World

SW Manager(策略中樞)

Contact 的主檔:匯入、清洗、分群(Segment)、觸發(Trigger)、素材(Asset)、App Integration(接 Ava)。決定「什麼時候、對誰、做什麼」。前端 samurai-world-client(Next.js),後端 samurai-world-backend。

Ava

Ava Messenger(互動引擎)

實際執行對話與通話:Conversation、Call、Bot 回覆、IVR、排程通話。決定「怎麼跟對方講話」。前端 ava-client,後端 ava(Laravel)。整合 Twilio / Quo / Pusher / Elasticsearch。

資料怎麼流(迴圈)

外部名單 ─► SW 建檔/清洗/分群
            │
            ▼
SW Trigger / App Integration ─► 呼叫 Ava API(以 Ava Account ID 為對接鍵)
            │
            ▼
Ava 建立 Lead / Journey ─► 發第一則訊息(Welcome / SendFirstMessageJob)
            │
            ▼
客戶回覆 ─► Ava ReplyMessageJob(AI 意圖偵測 → 一般回覆 / 預約通話)
            │
            ▼
Ava 透過 Webhook 回寫 SW(Journey Log / Opt-out)─► SW 顯示在 Contact Activities
🔑

對接鍵是 Ava Account ID。SW 在 App Integration 設定裡用 config.api_key 存 Ava account ID 來列 Ava Campaign;Contact 透過 external_lead_entity_id、traffic_source 同步到 Ava 成為 Lead。雙向事件閉環,就是 ContactLoop。

Opt-out(退訂)層級對應

退訂在三個層級各自獨立,跨系統要對齊:

Ava 層級對應到 SW影響範圍
account opt-outContactLead opt-out單一 Ava 帳號下的該聯絡人
organization opt-outContact opt-out整個組織下的該聯絡人
global opt-out同號碼的所有 Contact opt-out僅白名單帳號該電話號碼在白名單帳號範圍內退出,非真正全域
💬

在 Ava Conversations 頁面實際操作 opt-out。上面表格的三個層級不是抽象概念——Ava 的 Conversations 頁面(OptoutListLeadButton)就是讓客服直接選層級的地方。已 opt-out 的對話會顯示紅色圖示,滑鼠移上去顯示「Opt-out on {Level} Level」;未 opt-out 則有「Opt-out」按鈕,點下去可選 Account Level / Organization Level / Global Level 三選一,對應到 SW 這邊的 ContactLead opt-out、Contact opt-out、白名單帳號的跨卡查詢。確認彈窗文字是「This lead will be removed from your pipeline, and you won't receive any further updates.」——這是客服在 Ava 端按下去的動作,Webhook 回寫後才變成 SW 這邊看到的欄位。

⚠️

Opt-out 蓋的是「這張聯絡人卡」,不是「這支電話」。
把聯絡人想成一張張卡片:opt-out 蓋的章(contacts.is_opt_out / do_not_email,見 Contact::optOut())只蓋在那一張卡上。一般帳號判斷要不要發送時(Contact::isMarketable())只看這張卡自己有沒有章——如果同一支電話之後又匯入一筆新資料,系統會建一張全新、沒蓋章的卡,照樣觸發發送。這不是壞掉,是現行設計。

只有寫死在程式碼裡的白名單帳號(QuoteWizardAccountManager)在判斷時,才會多查一次「同支電話、白名單範圍內,有沒有任一張卡蓋過章」,有的話才擋下。目前的白名單:CLO(帳號 111/148/149/241/246-250/254-256/285/337)、Staging(帳號 29/83)。CL1 環境目前完全沒有這份白名單(空清單),所以 CL1 上任何帳號都只做「這張卡」的檢查,同電話換一筆新聯絡人一樣會被觸發——這是 CL1 QA 常見的「明明已經 opt-out 了怎麼又發訊息」的真正原因,先查是不是換了一筆新的 contact,而非系統故障。