總覽

從零認識 ContactLoop

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

兩大系統各做什麼

ContactLoop 由兩個互相呼叫的系統組成,合起來才是一個完整的「名單 → 觸發 → 對話 → 回寫」迴圈(Contact 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 Activities

Opt-out(退訂)層級對應

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

總覽

三個環境:stg / cl1 / prod

ContactLoop 有三個獨立部署的環境,各自有獨立的 SW 與 Ava、獨立的帳號與 Account ID。新人一律先在 stg 練習。

環境版本會落差(常見困惑來源)

stg 通常是最新版,cl1 / prod 的前端部署會晚一點跟上。例如 2026-08 實測:stg 的 Contacts 系列已改打 /api/contacts/grid,但 cl1 的 Marketing Sources / Endpoint Attributes / Technographics 三頁還在打舊版 /api/contacts?…size=500。測試裡這類情況會標成 xfail(預期失敗),部署跟上後自動轉 XPASS。看到 xfail 不是壞掉,是「已知環境落差」。

總覽

兩條上手路線,挑你那條

新人不一定都是工程師。這份指南分兩條路線,各自走完就能上工:

兩條路線都建議先讀上面的「ContactLoop 是什麼」與「三個環境」,後面的頁面功能章節則是共用參考。

SW 登入後導覽

登入 SW Manager 後,畫面長這樣Inside SW Manager after you log in

這一章帶你走一次登入後的整體畫面,再由上到下把左側選單的每個項目逐一介紹。選單結構取自 samurai-world-client 的 src/app/configs/routes.tsx;有 需 system-admin、功能旗標、開發中 標記的項目,在某些環境或帳號會看不到,屬正常。

① 整體畫面:頂部列 + 左側選單 + 主內容

② 頂部列三個區塊細講

③ 左側選單逐項(由上到下)

頁面功能

SW Manager 各頁面功能

以下清單整理自 samurai-world-client 的 src/pages 路由與 auto_cl 的頁面 → API 對應表。新版 / 舊版 / 需 admin 標出權限或版本狀態。

Home / 總覽

Contacts 系列(聯絡人)

Actions 系列(Ava 互動紀錄)

Reports(舊版報表)

策略與設定模組

合規 / 營運設定

組織 / 帳號 / Admin

Ava 登入後導覽

登入 Ava Messenger 後,畫面長這樣Inside Ava Messenger after you log in

Ava Messenger(ava-client)是營運人員看對話、通話、Bot 的地方。這一章先帶整體畫面,再把左側選單逐項介紹。Ava 跟 SW 最大的 UI 差別:帳號選單是階層式 Cascader(Account ▸ Campaign),且左側選單會依「有沒有選 Account / 有沒有進入 Campaign」切換成三種內容。標記:僅 system-admin、限特定角色、開發中/預留。

① 整體畫面:頂部列 + 左側選單 + 主內容

② 頂部列三個區塊細講

③ 左側選單逐項(三種情境)

情境 A · 帳號層級選單(選了 Account、沒進 Campaign)

來源:AccountsMenuItems(activeAccountId),尾端接 Admin 群組。路由前綴 /accounts/{aid}/…。Source: AccountsMenuItems(activeAccountId), with the Admin group appended. Routes are prefixed /accounts/{aid}/….

情境 B · Campaign 內選單(從 Cascader 選了某 Campaign,或從 Campaigns 頁進入)

來源:CampaignsMenuItems(activeCampaignId)。路由前綴 /campaigns/{cid}/…。子項少於 2 個的群組會被「攤平」成頂層項目(shouldFlattenChildrenWhen)。Source: CampaignsMenuItems(activeCampaignId). Routes prefixed /campaigns/{cid}/…. Groups with fewer than 2 children are flattened into a top-level item (shouldFlattenChildrenWhen).

情境 C · 未選 Account(只剩 Admin 群組)

來源:AdminMenuItems() 單獨渲染。內容同上面「Admin 群組」的 9 個子項(Contexts / Organizations / Accounts / Users / Internal Performance Stats / Intent Knowledge Base / Holiday Settings / API Keys / Short Codes),全部 僅 system-admin。一般使用者通常不會停在這個情境——登入後會自動帶入帳號層級選單。Source: AdminMenuItems() rendered alone. Same 9 children as the Admin group above (Contexts / Organizations / Accounts / Users / Internal Performance Stats / Intent Knowledge Base / Holiday Settings / API Keys / Short Codes), all system-admin only. Normal users rarely land here — login normally drops them into the account-level menu.

頁面功能

Ava Messenger 各頁面功能

Ava Messenger(ava-client)是營運人員看對話、通話、Bot 的地方。SW 負責「對誰做什麼」,Ava 負責「實際講話的過程」。

Auth(登入/註冊/忘記密碼)逐鍵詳解

從 0 開始 · 路線 A

從 Ava 建帳號到 SW Segment 設定完成

這條路線是一條跨系統的完整流程:先在 Ava Messenger 建立一個新的 Account 並開出 API Key,再到 SW Manager 用那組 Key 接上、匯入名單、把 Segment 設到好。全程以 stg 環境為例,不碰任何程式碼。

Phase 1 · Ava 端 — 建立帳號、Bot、Campaign

1. 取得 Ava 登入帳號(signup 目前是 stub)

   ⚠️ 注意:/auth/signup 頁面目前是 stub——填 Nickname/Email/Password 送出後只會跳「Account created. Please check your inbox!」提示,不會呼叫任何 API、不寄確認信、也不會真的建帳號。所以登入帳號請改由已存在的 system-admin 建立再提供給你。stg 環境大多數 user 拿到的都是 system-admin 權限,可直接用來跑後續流程。這一步建立的是「登入使用者」,還不是業務 Account(業務 Account 在下面「建立新的 Ava Account」步驟建)。

2. 登入 Ava Messenger

   確認信完成後到 /auth/signin 用 Email + Password 登入,進入 Ava 主畫面。stg / cl1 / prod 是三套獨立的 Ava,帳號不互通。

3. 建立新的 Ava Account

   從 admin 進入 Account 列表(/accounts)後,點右上角 Create 建立新 Account。必填:Name(帳號名)、Transfer Phone Number(轉接號碼,預設走 Dial Transfer,之後可在 Settings 改 Streaming Transfer)、Organization(所屬組織,下拉選)。

   img/AVA1.png

   ⚠️ Inherit Existed Twilio Account 欄位請務必依照A2P 詳解裡「各環境要 Inherit 哪個帳號」的對照表填(stg / prod / cl1 各不同)——若這裡沒設定,新 Account 會沒有 A2P 資格,之後無法發送任何 SMS 或撥打電話。
   🔒 權限:/accounts 屬於 Admin 群組(roles: [] = 僅 system-admin),Cascader 的「Create New Account」也需要 ACCOUNT_CREATE 權限——所以這一步必須用 system-admin 帳號。stg 環境大多數 user 都是 system-admin,可直接做;若你不是,請找 system-admin 協助建 Account。
   建立完成後刷新頁面,再進入剛建立的 Account 做接下來的設定。💡 小提示:在 Account 列表找剛建立的那筆,可以點 ID 欄排序,最新建立的會排到最上面(或最下面,依排序方向)。

4. 在帳號設定產生 API Key

   進入剛建的 Account → Settings(/accounts/{accountId}/settings),切到 API tab → 建立 API Token。把產生的 API Token 與這個 Account 的 Account ID 一起記下來——這兩個值待會要貼進 SW。Settings 共有 Main / Call / Transfer / API / A2P 五個 tab,只有 API tab 需要在這一步完成。

5. 建立 Bot(Campaign 的必要前提)

   ⚠️ 要先建立 Bot,否則無法建立 Campaign。一樣點右上角 Create 建立新 Bot(/accounts/{accountId}/bots/create)。

   img/AVA2.png

   欄位:Name;Type 選 Fusion KB(另一個選項 DialogFlow 需要 user 先跟 Google 連通帳號,暫時不用管);Welcome Message——這則訊息只有在 Ava → Bots → Chat Simulator 測試時會出現,平常用實體號碼測試不會看到它,屬正常現象,不是沒設定成功;Reply Mode 由上到下是 Fixed(死板)→ Guided → Flexible(靈活);Intent Group 一開始可以先選前面有 - 前綴的四個(用 Transfer 元件從 Available 移到 My Intent Groups),之後有需求再自行新增。

6. 建立 Campaign

   Bot 建好後,一樣點右上角 Create 建立新 Campaign。精靈只需要填 Name,其他步驟(Default Language、Default Timezone、後續的 IVR/Conversation 設定)都有預設值,一路按 Continue 到底即可——這些之後都能回 Campaign Settings 再調整。

7. 回 Campaign Settings 綁 Bot + 設定對話頻道(P0)

   要讓 Ava 真的能回話,回到這個 Campaign 的 Settings 至少把 P0 設好:
   ① Bot tab — 把剛建的 Bot 綁定到這個 Campaign(沒綁,Ava 不會自動回話,只會收到 SW 發的首則訊息)。
   ② Conversation tab → Conversation Channel — 設定 campaign 走的頻道,需與 SW 端 Asset 的 Interaction Type 對應。
   門號(Phone Numbers 綁號)、轉接(Transfer tab)、營業時段(Business Hours)屬 P1,第一次跑可後補。完整的 5-tab 詳解與優先度排序見 Ava Campaign Settings 詳解。

8. 確認 Account ID 與 Campaign ID 都已記錄

   以上是 Ava 建立新 Account 的完整步驟。收尾前務必確認沒有遺漏:Account ID(Account 列表 Name (ID: nn))和 Campaign ID(Campaign 列表同樣格式)都要存在、記錄下來——接下來 SW 那邊(Phase 2)的 Asset / Integration 都會用到。

Phase 2 · SW 端 — 建 Account、接上 Ava、完成 Segment

1. 登入 SW Manager 並建立新 Account

   開 https://staging.sw.onramplab.com/auth/signin,輸入 SW 的 Email + 密碼登入(看到 "home" 字樣即成功)。從 settings/admin 進入 Accounts 列表,點右上角 Create 建立新 Account。

   img/SW1.png

   表單裡兩個欄位要特別注意:
   ⚠️ Phone Verification 開啟的話,非美國的正式號碼會被阻擋並加入黑名單——如果客戶名單有海外門號,先確認這個開關的影響。
   ⚠️ Blacklist Check Enabled 開啟的話,匯入時會檢查號碼是否在一些已知黑名單裡。
   💡 Redirect Domain 先跟著外面其他 Account 填一樣的值就好,不用自己另外想。

2. 把新 Account 加入 Organization,再把 Organization 指給你的 User

   ⚠️ 建立完 Account 後,即使刷新頁面,也沒辦法在帳號切換器上馬上看到剛建立的 Account——這不是壞掉,是因為新 Account 還沒被指派給任何人。要讓自己的 User 看得到它,需要兩步:
   ① 進 admin → Organization,把剛建的 Account 加入一個 Organization(attachAccounts,只能選還沒被任何 Organization 綁定的自由帳號)。
   ② 進 admin → Users,編輯你自己的 User,在 Organizations多選欄裡把該 Organization 加進去——User 會 inherit 這個 Organization 底下所有 Account(唯讀顯示在下方確認)。

   img/SW2.png

   img/SW3.png

3. 切換到新 Account,建立 App Integration(接 Ava)

   點左上角 logo 離開 admin 頁面,用帳號切換器切到剛新增的 Account。點 settings/admin 進入 /app-integrations,一樣點右上角 Create 建立新的 App Integration。

   img/SW4.png

   Type 選 Ava。這個表單只有兩個欄位:Account ID——這裡填的其實是 Phase 1 拿到的 Ava Account ID(目前實作把它存進後端叫 api_key 的欄位,是暫時的技術債,不代表要另外填一組 API Key);Sandbox checkbox——在 stg 環境一定要勾選 Sandbox,才能連到 Ava。沒設這一步,後續 Action 呼叫 Ava 不會生效。

4. 到 Configuration 建立 Asset

   建好 App Integration 後,到左側選單的 Configuration 群組建立 Asset——⚠️ 每個 App Integration 有自己的子項目,要在剛建立的那個 App Integration 名稱底下建 Asset,別選錯了。一樣點右上角 Create。

   img/SW5.png

   先確認 App Integration 名稱是不是選對了那個 Ava 整合,再選 Interaction Type(目前 Ava 只有兩種:Message / Call)、選 Campaign。如果 Interaction Type 選 Message,需要填 Template 作為 Ava 要傳送的訊息內容;選 Call 則不用填。

5. 到 Configuration 建立 Segment

   一樣在 Configuration 裡,點右上角 Create 建立新 Segment。

   img/SW6.png

   表單上半部的 Rules(資料篩選)是觸發條件設定——決定哪些聯絡人算命中這個 Segment。下半部從 Reschedule Rule 開始一路到底的欄位(Type、Business Hours、TCPA、Holiday 等)是觸發時間設定——決定命中的聯絡人「什麼時候」被真正觸發。存檔後頁面會直接接著要求你設定 Action。

6. 設定 Action(選 Channel,可行內建立 Asset)

   img/SW7.png

   Channel 要跟剛剛建立的 Asset 對應:
   · 若 Asset 是 Message → Channel 選 SMS。
   · 若 Asset 是 Call → Channel 選 Active Dials。
   · Other 是給非 Ava 在用的其他整合類型選的,這條路線用不到。
   💡 如果前面沒有先建好 Asset,也可以在這個畫面直接建立:先選好 Channel 和要建在哪個 App Integration 底下,再點下面的 Create Asset 按鈕,彈出的表單就是完整的 Asset 建立流程。
   ⚠️ 關鍵:在下拉選單裡選好要用的模板(Asset)後,一定要點旁邊的 Add 按鈕——不點 Add,選擇不會生效,Action 就等於沒接上任何 Asset。

7. 匯入聯絡人(Contacts)

   Contacts 選單 → Import Contact(stg 新版會在新分頁開啟)。貼上 CSV,欄位:phone, first_name, last_name, email, external_lead_id, traffic_source。匯入後,命中 Segment 規則的聯絡人會觸發「已指派給該 Segment 的 Action」,Action 再透過 App Integration 呼叫 Ava 發送(首則訊息 / 外呼)。⚠️ 若 Action 沒建或沒指派給 Segment,匯入只會把聯絡人寫入 SW,不會觸發任何訊息——這是「匯入了卻沒動」最常見的原因。

8. 查看 Contacts-27 聯絡人資料

   到 /contacts-27 開啟聯絡人總覽(新版 ag-grid,進頁會打 /api/contacts/grid,回應 data.rows / data.lastRow)。在這裡確認剛匯入的聯絡人是否出現、用欄位排序與篩選查看 phone / first_name / last_name / email 等欄位。2026-08 起前端已改打 grid API,舊的 size=500 列表行為已不適用;若要對照舊版,可看 /contacts(old,size=20)或 /contacts-2026(old,size=500),新人日常請以 Contacts-27 為準。

流程總覽(整條從頭到尾的一頁式總圖)

Ava 登入帳號(由 system-admin 建立;signup 是 stub)→ Ava signin
   │
   ▼
Ava /accounts → Create New Account(Name + Transfer Phone + Organization)〔需 system-admin〕
   │  產生 Ava Account ID
   ▼
Ava Account → Settings → API tab → 建 API Token
   │  拿到 Ava Account ID + API Key  ←── 整條流程的「橋」
   ▼
Ava Campaign Settings(P0:Bot + Conversation Channel;門號/轉接/營業時段 P1 後補)
   │
   ▼
SW signin → 選 SW Account
   │
   ▼
SW /app-integrations → Type=Ava,Account ID 填 Ava Account ID,stg 勾選 Sandbox
   │
   ▼
SW /assets → 建 Asset(樣板 + 變數 + Ava Campaign = 發什麼)
   │
   ▼
SW /segments → 建 Segment(規則 = 對誰 + Trigger 何時)→「Next - Create Action」
   │
   ▼
SW 建 Action(Channel + App Integration + 選 Asset)→ 指派回 Segment(action_id)
   │
   ▼
SW Import Contacts(命中規則者 count +1 → 觸發【已指派給 Segment 的 Action】→ Ava 發訊息)
   │
   ▼
SW /contacts-27 → 查看聯絡人資料
   │
   ▼  Phase 3 · 回 Ava 確認訊息與行為執行
Ava Cascader 選 Account/Campaign → Conversations 看對話 + 首則訊息 + Bot 回話
   │
   ▼
Ava Stats(Call Performance / Conversion)→ 確認行為有執行 ✓ 完成

Phase 3 · 回 Ava 確認訊息與行為有執行

前面 Phase 2 在 SW 做的事,最終都要回 Ava 這一端驗證真的發生了。這是整條流程的收尾,也是判斷「有沒有接起來」的依據。

1. 切回 Ava,選剛建的 Account / Campaign

   回到 Ava Messenger,用頂部 Cascader 選 Phase 1 建的 Account,再進入該 Account 下的 Campaign(SW 端 Asset 的 Campaign 下拉選的就是這個)。選了會 router.push('/') 進 Campaign Dashboard,左側選單同時切換成「情境 B · Campaign 內選單」。Back in Ava Messenger, use the top Cascader to pick the Account from Phase 1, then enter a Campaign under it (the same one the SW Asset's Campaign dropdown selected). Selecting does a router.push('/') into the Campaign Dashboard, and the left sidebar switches to the "Context B · in-campaign" menu.

2. 到 Conversations 看對話是否出現

   左側 Conversations → /campaigns/{cid}/conversations。確認剛匯入的聯絡人有出現一則對話,且SW 觸發的首則訊息(Asset 的 Template 內容)已送達。若前面「回 Campaign Settings 綁 Bot」步驟的 Bot tab 有綁 Bot,會看到 Ava 自動回話——這就是「Ava 行為有執行」最直接的證據。若 Bot 沒綁,只會看到單向的首則訊息(沒有自動應答),此時行為算「訊息送達但未應答」。Left sidebar Conversations → /campaigns/{cid}/conversations. Confirm each imported contact shows a conversation thread and that the first message triggered by SW (the Asset's Template content) was delivered. If you attached a Bot in the earlier "attach the Bot in Campaign Settings" step's Bot tab, you'll see Ava auto-reply — the most direct evidence that "Ava behavior executed." With no Bot attached you'll only see the one-way first message (no auto-reply); in that case the status is "message delivered, not answered."

3. 到 Stats 確認行為有執行

   左側 Stats 群組:Call Performance Stats(所有角色可見)看發送/通話數;Conversion Stats(Owner/AccountAdmin)看轉換。計數 > 0 代表 Action 確實被觸發並送到 Ava 執行。也可回帳號層 Stats 看 Campaign Performance 當整體對照。Left sidebar Stats group: Call Performance Stats (all roles) for send/call counts; Conversion Stats (Owner/AccountAdmin) for conversions. A count > 0 means the Action was actually triggered and executed on the Ava side. You can also check account-level Stats → Campaign Performance for an overall comparison.

4. 通過標準(什麼算「接起來了」)

   同時滿足以下即算成功:
   ① Contacts-27 看得到匯入的聯絡人(資料有進 SW);
   ② Ava Conversations 看得到對話 + 首則訊息已送達(訊息有到 Ava);
   ③ Ava Stats 計數 > 0(Action 確實被觸發執行);
   ④ (若有綁 Bot)Conversations 看得到 Ava 自動回話(Bot 行為有執行)。Success means all of the following hold:
   ① Contacts-27 shows the imported contacts (data made it into SW);
   ② Ava Conversations shows the thread + the first message delivered (the message reached Ava);
   ③ Ava Stats count > 0 (the Action was actually triggered and executed);
   ④ (if a Bot is attached) Conversations shows Ava auto-replying (Bot behavior executed).

從 0 開始 · 路線 B

QA 工程師:從 0 跑出第一套測試

auto_cl 是 ContactLoop 的 E2E 自動化測試專案(Python + Playwright),跑通它就等於把 SW ↔ Ava 整條迴圈驗過一遍。目標:在本機跑出 stg 的綠燈報告。

測試覆蓋哪些事

安裝步驟

# 1. 建立虛擬環境並安裝套件
python -m venv venv
source venv/bin/activate          # Windows: venv\Scripts\activate
pip install -r requirements.txt

# 2. 安裝 Playwright 瀏覽器
playwright install chromium

# 3. 複製環境變數範本並填入
cp .env.example .env              # Windows: copy .env.example .env

.env 必填欄位(以 stg 為例)

跑測試

# Windows 先設編碼
$env:PYTHONUTF8=1

# 全部測試(自動排序:IP → Nucleus → 頁面 API → Segments → AvaLink)
pytest --env stg -v

# 只跑某一支
pytest tests/test_sw_segments.py --env stg -v

# 只跑 Ava 相關 / 排除 SMS
pytest -m Ava --env stg -v
pytest tests/test_sw_nucleus.py --env stg -v -m "not Sms"

# 跑單一方法
pytest tests/test_sw_segments.py::TestSW::test_sw_segments_count2 --env stg -v

產出物在哪

• reports/report.html — HTML 測試報告
• reports/test.log — 完整 log
• videos/ — 每次執行的單一連續影片(.webm,檔名帶環境與時間戳)
• reports/ava_link_issues.json — Ava 連結異常(有異常才產生)
• reports/sw_page_api_issues.json — SW 頁面 API 檢查異常
• reports/api_metrics.json — API 回應時間統計
• 測試結束自動寄 Email / Teams 通知(若已設定)