總覽Overview
從零認識 ContactLoopGetting to know ContactLoop
這份指南把新人從「不知道 ContactLoop 是什麼」一路帶到「能在 stg 環境建一個帳號、跑出一套測試」。內容來自實際 repo(samurai-world、ava、auto_cl)的程式碼與內部文件,不是憑空想像。This guide takes new hires from "never heard of ContactLoop" to "can create an account in stg and run a test suite." Content is sourced from the actual repos (samurai-world, ava, auto_cl) code and internal docs — not imagined.
兩大系統各做什麼What each system does
ContactLoop 由兩個互相呼叫的系統組成,合起來才是一個完整的「名單 → 觸發 → 對話 → 回寫」迴圈(Contact Loop 由此得名)。ContactLoop is made of two systems that call each other. Together they form a complete "list → trigger → conversation → write-back" loop — which is where the name Contact Loop comes from.
SW Manager(策略中樞)SW Manager (strategy hub)
Contact 的主檔:匯入、清洗、分群(Segment)、觸發(Trigger)、素材(Asset)、App Integration(接 Ava)。決定「什麼時候、對誰、做什麼」。前端 samurai-world-client(Next.js),後端 samurai-world-backend。The master record of Contacts: import, cleaning, segmentation (Segment), triggers (Trigger), assets (Asset), and App Integration (connecting to Ava). It decides "when, to whom, what." Frontend samurai-world-client (Next.js), backend samurai-world-backend.
Ava Messenger(互動引擎)Ava Messenger (interaction engine)
實際執行對話與通話:Conversation、Call、Bot 回覆、IVR、排程通話。決定「怎麼跟對方講話」。前端 ava-client,後端 ava(Laravel)。整合 Twilio / Quo / Pusher / Elasticsearch。Actually runs the conversations and calls: Conversation, Call, Bot replies, IVR, scheduled calls. It decides "how to talk to the person." Frontend ava-client, backend ava (Laravel). Integrates Twilio / Quo / Pusher / Elasticsearch.
資料怎麼流(迴圈)How data flows (the loop)
外部名單 ─► 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 ActivitiesExternal list ─► SW create/clean/segment
│
▼
SW Trigger / App Integration ─► calls Ava API (Ava Account ID is the join key)
│
▼
Ava creates Lead / Journey ─► sends first message (Welcome / SendFirstMessageJob)
│
▼
Customer replies ─► Ava ReplyMessageJob (AI intent detection → general reply / book a call)
│
▼
Ava writes back to SW via Webhook (Journey Log / Opt-out) ─► SW shows in Contact Activities
對接鍵是 Ava Account ID。The join key is the Ava Account ID.SW 在 App Integration 設定裡用 config.api_key 存 Ava account ID 來列 Ava Campaign;Contact 透過 external_lead_entity_id、traffic_source 同步到 Ava 成為 Lead。雙向事件閉環,就是 ContactLoop。 In App Integration settings, SW stores the Ava account ID in config.api_key to list Ava Campaigns; a Contact syncs to Ava as a Lead via external_lead_entity_id and traffic_source. That bidirectional event loop is ContactLoop.
Opt-out(退訂)層級對應Opt-out levels mapping
退訂在三個層級各自獨立,跨系統要對齊:Opt-out is independent across three levels; they must align across systems:
| Ava 層級Ava level | 對應到 SWMaps to SW | 影響範圍Scope |
|---|---|---|
| account opt-out | ContactLead opt-out | 單一 Ava 帳號下的該聯絡人That contact under one Ava account |
| organization opt-out | Contact opt-out | 整個組織下的該聯絡人That contact across the whole organization |
| global opt-out | 同號碼的所有 Contact opt-out僅白名單帳號All Contacts with the same numberwhitelisted accounts only | 該電話號碼在白名單帳號範圍內退出,非真正全域That phone number opts out within the whitelisted account set — not truly global |
在 Ava Conversations 頁面實際操作 opt-out。Where opt-out is actually triggered: the Ava Conversations page.上面表格的三個層級不是抽象概念——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 這邊看到的欄位。The three levels in the table above aren't abstract — Ava's Conversations page (OptoutListLeadButton) is where an agent actually picks a level. An already-opted-out conversation shows a red icon with a "Opt-out on {Level} Level" tooltip; otherwise there's an "Opt-out" button offering Account Level / Organization Level / Global Level, which map to SW's ContactLead opt-out, Contact opt-out, and the whitelisted-account cross-card lookup, respectively. The confirmation dialog reads "This lead will be removed from your pipeline, and you won't receive any further updates." — this is the action an agent takes on the Ava side; it becomes what you see on the SW side only after the webhook writes it back.
Opt-out 蓋的是「這張聯絡人卡」,不是「這支電話」。Opt-out stamps this contact record, not this phone number.
把聯絡人想成一張張卡片: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,而非系統故障。
Think of each contact as a card. The opt-out stamp (contacts.is_opt_out / do_not_email, set by Contact::optOut()) is stamped on that one card only. For normal accounts, the send-eligibility check (Contact::isMarketable()) only looks at that card's own stamp — if the same phone number is imported again later, the system creates a brand-new, unstamped card and happily triggers it. This isn't a bug; it's the current design.
Only accounts hardcoded into a whitelist (QuoteWizardAccountManager) get an extra check: "does any card with this same phone number, within the whitelisted accounts, already have a stamp?" — and only then is the send blocked. Current whitelist: CLO (accounts 111/148/149/241/246-250/254-256/285/337), Staging (accounts 29/83). The CL1 environment currently has no whitelist at all (empty list), so on CL1 every account only checks "this one card" — importing the same phone number as a new contact will trigger it again. This is the real cause behind the common CL1 QA finding of "I opted this out, why did it send again?" — check whether a new contact record was created before assuming a system bug.