為聊天介面加上品牌色彩 — 顏色與標誌

原則 — 提供一種顏色，而不是一組配色。 前景顏色會在儲存時由此衍生，因此所有組合都能保持可讀性。自行挑選文字顏色，就是讓按鈕完全無法閱讀的作法。

品牌識別（Branding）存在於 share 中，而非 agent：同一個 agent 在某個網站可以是白標小工具，在另一個地方則只是一般連結。因此請先取得 token。

list_shares(agent_name="mortgage-advisor")
# → [{ token: "RuqY…", label: "Website widget", config: { theme_color: "#F7B331", … } }]
 
configure_share(
  agent_name="mortgage-advisor",
  token="RuqY…",
  theme_color="#F7B331",
  logo_url="https://cdn.example.com/brand/mark-512.png",
)

只有您傳入的欄位會變更 —— 其餘設定維持不變。

重新命名 share

label 是聊天頁面頂部與瀏覽器分頁標題顯示的名稱。它是 configure_share 中的一個欄位，與其他欄位一樣：

configure_share(agent_name="mortgage-advisor", token="RuqY…", label="Pip — reading buddy")

您不需要建立新的 share 並刪除舊的 share 來進行重新命名。 新的 share 會產生新的 token，導致已嵌入客戶網站中的連結失效 —— 可見的名稱與網址並不相同，且只有名稱是在上線後可以安全變更的。

第二種顏色，僅在品牌有第二色時提供

大多數品牌只有一種顏色，不需要此處的任何設定。有些品牌有主要顏色與強調色 —— 將第二個顏色作為 highlight_color 傳入，它將用於需要可見但不與主要動作競爭的場合：

configure_share(
  agent_name="pip",
  token="ENhs…",
  theme_color="#0B4230",      # primary: buttons, the current storyline step, user bubbles
  highlight_color="#D9A922",  # highlight: second chart series, citation markers
)

其前景顏色會在儲存時與主要顏色一樣進行衍生，因此相同的可讀性保證依然成立。省略它則任何地方都不會變更 —— --acc-2 會回退至主要顏色，這是每個單一顏色品牌所需且無需設定的。

不要手動擴散它。 您 可以 從 custom_css 覆蓋我們的元件類別，但您會後悔：這些類別名稱是我們的內部實作，它們會變更，且一旦變更，您的品牌識別會靜默失效。設定這兩種顏色，讓元件決定每個顏色該用在哪裡。

顏色：傳入一個，獲得四個

theme_color 是品牌的主要顏色，格式為 #RGB 或 #RRGGBB。儲存時，平台會根據 WCAG 對比度衍生前景顏色並儲存：

淺色品牌顏色因此會獲得 深色 文字，而非白色。#F7B331 搭配白色文字的對比度為 1.83:1 —— 低於 UI 元件的 3:1 底線，意味著標籤確實無法閱讀；衍生的深色前景對比度為 10.21:1。

不要自行計算配色，也不要嘗試設定文字顏色 —— 它們由伺服器衍生，您的值會被覆蓋。傳入一種顏色就是全部工作。

清除它（theme_color=""）也會刪除衍生值，並將小工具恢復為預設藍色。未設定它也會達到相同效果 —— 內建 token 已經是匹配的配對。

Logo：長寬比決定其使用位置

傳入絕對 URL。Logo 出現在兩個具有不同限制的位置：

• 標題列 —— 高度對齊，寬度自由。任何長寬比均可，包括寬幅字標（wordmark）。
• 折疊氣泡 —— 正方形，因為 Logo 就是 氣泡的形狀。僅使用 0.74 到 1.35 之間的長寬比；寬幅字標會回退至平台圖示，而非被擠壓成無法閱讀的細長條。

因此，對於寬幅字標，實際答案是 兩個檔案：標題列的字標，氣泡的方形標誌。如果客戶只有字標，標題列仍會顯示其品牌，氣泡顯示中性圖示 —— 這比無法閱讀的細長條更好。

不要將字標裁切為正方形。裁切會留下半個單詞，這就不再是他們的商標。

當品牌指南覆蓋一切時

某些客戶有嚴格的配色，不會遵循我們的任何主題。custom_css 在品牌變數之後注入，因此純宣告已經會勝出 —— 不需要 !important。（過去是必需的，因為顏色是作為內聯樣式設定的。現在不是了。）

⚠️ 在編寫任何 CSS 之前請閱讀此內容

您必須編寫兩個區塊：:root 用於淺色，html[data-theme="dark"] 用於深色。

:root 在 兩種 主題中均匹配，並優先於平台的深色規則（相同優先級，且您的規則在後）。因此，僅在 :root 下編寫的配色意味著 訪客的淺色/深色切換完全無效 —— data-theme 會翻轉，但沒有變數跟隨它。

這已經在生產環境中發生過：一個 agent 在 :root 下放置了完整的深色配色，頁面看起來很棒，主題按鈕變成了一個無人察覺的死控制項，持續了數週。頁面看起來正確，這正是此問題未被報告的原因。

如果客戶確實只需要一種主題，請將 share 的 theme 欄位設定為 light 或 dark。這會 隱藏 切換按鈕，而非破壞它。

正確的形狀 —— 複製此內容並替換值：

/* LIGHT — the light values go here, not the dark ones */
:root{
  --acc: #6b21a8;        /* brand primary — backgrounds, focus rings */
  --acc-fg: #ffffff;     /* text on --acc: YOU own the contrast here */
  --acc-text-l: #581c87; /* brand colour used as text, light theme */
  --bg: #fdfbff;
  --surface: #ffffff;
  --text: #1e1b2e;
  --border: #e6e0f0;
}
/* DARK — required whenever you touched --bg / --surface / --text above */
html[data-theme="dark"]{
  --acc: #a855f7;
  --acc-fg: #1a0b2e;
  --acc-text-d: #c084fc; /* note: -d, the dark-theme variant */
  --bg: #120c1d;
  --surface: #1c142b;
  --text: #f0e9ff;
  --border: #32254a;
}

這是值得覆蓋的完整集合 —— 小工具刻意使用少量顏色。

哪些變數需要深色區塊？描述 表面 的變數，因為它們在主題之間反轉：--bg、--surface、--text、--border。--acc 是品牌顏色，通常在兩種主題中保持相同，儘管範例在深色主題中使其更亮，因為深紫色在近乎黑色的背景上難以看見。

另外兩點請牢記：

• custom_css 不提供可讀性保證。 theme_color 提供。僅在衍生無法表達的場合使用 CSS，並保持 theme_color 設定為基準。
• 將 --acc-text-l 和 --acc-text-d 設定為相同的值會使其目的失效。 它們的存在正是為了讓品牌顏色在相反背景上作為文字時可讀。

configure_share 在檢測到單一的 :root 錯誤時會返回 warnings 陣列 —— 請閱讀它。控制台在 CSS 編輯器旁邊顯示相同的警告。

css_url 載入外部樣式表，供那些保留自己主題檔案的客戶使用。

您的顏色驅動的互動控制項

聊天中每個帶有強調色的控制項都讀取相同的配對 —— 背景 --acc，文字 --acc-fg：

已選取行預設已設定樣式 —— 品牌色邊框、行後方 10% 品牌調色，以及使用 accent-color 繪製的原生控制項 —— 均由 --acc 驅動，因此設定 theme_color 再次成為全部工作。語音按鈕的錄音光暈同樣衍生自 --acc（透過 color-mix 以 22%/55% 透明度），因此它會自動以品牌顏色脈衝；僅在有意採用不同處理方式時，才在 custom_css 中覆蓋它：

/* softer, wider recording glow — both themes if you also touch surfaces */
:root .ca-talk.rec{
  box-shadow: 0 0 0 3px color-mix(in srgb, var(--acc) 15%, transparent),
              0 0 40px color-mix(in srgb, var(--acc) 40%, transparent);
}

僅在品牌指南要求不同處理方式時才使用 CSS：

/* stronger selected state, both themes (remember the two-block rule above) */
:root .ca-form label:has(input:checked){
  border-color: var(--acc);
  background: color-mix(in srgb, var(--acc) 18%, transparent);
  font-weight: 600;
}
html[data-theme="dark"] .ca-form label:has(input:checked){
  background: color-mix(in srgb, var(--acc) 24%, transparent);
}

保持所有內容可讀的規則：任何使用 --acc 繪製的元素，其文字來自 --acc-fg —— 絕非文字顏色。 經典的失敗是在深色區塊中將 --acc 覆蓋為淺色品牌黃色，並保留白色文字：Ask 表單按鈕變成黃底白字，對比度為 1.8:1，客戶回報「深色模式下表單按鈕無法閱讀」。如果您在 custom_css 中覆蓋 --acc，您必須在 同一區塊、兩種主題 中擁有 --acc-fg —— 或者更好，根本不要為此使用 CSS：設定 theme_color，平台會為您衍生合規的 --acc-fg。

使聊天可安裝（PWA）

獨立聊天頁面（/s/… 連結、QR 碼及下方的別名網址）是可安裝的應用程式：訪客可以將它們新增至主畫面，使用您自己的圖示和名稱。兩個旋鈕，每個 agent 設定 —— 安裝至主畫面的是該 agent 的入口頁面，因此每個 agent 都是具有自己圖示的獨立應用程式（支援 agent 和預售 agent 安裝為兩個不同的應用程式）：

set_pwa_branding(
  agent="support",                                                # which agent's install branding
  icon_source_url="https://cdn.example.com/brand/mark-1024.png",  # ONE square master image ≥192×192
  install_prompt="banner",                                        # banner (default) | card | off
)

• 主影像僅擷取一次，平台會生成整個集合 —— 瀏覽器分頁圖示、192/512 安裝圖示和 Android 可遮罩變體。非方形主影像會居中裁切，因此使用方形 標誌，而非寬幅字標。
• install_prompt 控制訪客在聊天頁面看到的内容：banner 是一個可關閉的細長橫幅（Android/Chrome 觸發系統安裝對話框；iOS 獲得「分享 → 新增至主畫面」引導，因為 Apple 不提供 API），card 是更顯眼的首次訪問卡片，off 禁用邀請。關閉狀態會按訪客記住。
• 圖示是 可選的 —— 沒有它們則使用平台圖示。僅傳入 agent 名稱以讀取該 agent 的目前設定。

您交給人的連結

當租戶別名 和 agent 別名均設定時，create_share / list_shares 會返回 pretty_url —— https://chat.agent4.io/t/<租戶別名>/<agent別名>。這是提供給人們並印在材料上的連結：易讀、易記，且它會倖存於 token 旋轉（平台會延遲維護其後面的 share）。/s/<token> 形式仍保留給嵌入和機器使用。

回應中沒有 pretty_url？別名未設定 —— 修正此問題，而非發送 token 連結：agent 別名透過 create_agent(alias=…) 或 PUT /agents/{name}/alias；租戶別名位於控制台 → 設定。設定 agent 別名本身即為發布動作：別名頁面在首次訪問時自動建立匿名 share。

客戶自己的網域

託管聊天頁面可以在客戶的網域上提供服務 —— https://chat.client.com/ 顯示其品牌頁面，憑證自動簽發。

set_custom_domain(domain="chat.client.com", agent_alias="menu")
# → { status: "pending", cname_target: "endpoint.agent4.io", last_error: "…" }

順序很重要，且它是非同步的：

1. 告知客戶在他們的子網域新增 CNAME 至回應中的 cname_target（endpoint.agent4.io）。僅限子網域 —— 頂層網域（client.com）無法使用 CNAME；讓他們使用 chat.client.com，或使用具有 CNAME 扁平化的 DNS 供應商。
2. 在 Cloudflare 上，記錄必須僅為 DNS（灰雲）。 代理記錄解析為 Cloudflare 的 IP，驗證會失敗 —— last_error 會明確說明，並顯示觀察到的地址。這是最常見的失敗；在猜測之前請閱讀 last_error。
3. 驗證每 10 分鐘自動重新執行；再次呼叫 set_custom_domain（相同參數）或檢查 tenant_info() 以查看目前狀態。active 表示已上線 —— 首次訪問會簽發憑證。

每個工作區一個網域。agent_alias 為空會落在租戶的品牌頁面上；設定它會直接落在單一 agent 的聊天上。現有的 chat.agent4.io 連結保持運作 —— 這是額外的入口，而非替代品 —— 且聊天身分是按網域的：訪客在 chat.agent4.io 上的歷史記錄不會跟隨他們到自訂網域。

需要包含自訂網域的方案（403 = 租戶需要升級）。

對話搜尋模態（Spotlight）

獨立頁面和網頁客戶端具有 ⌘K 對話搜尋。它自動遵循品牌 —— 模態讀取與所有其他元件相同的變數（--surface、--border、--text、--muted、--overlay、--surface-hover、--accent-soft，以及高亮匹配項的 --acc-text 配對） —— 因此 設定 theme_color 在此處也是全部工作。

對於需要更多的品牌指南，類別名稱是穩定的，且 custom_css 優先於元件自己的樣式：

/* rounder panel, brand-tinted selected row — remember the two-block rule above */
:root{ }
.ca-ss{ border-radius: 20px; }
.ca-ss-item.sel{ background: color-mix(in srgb, var(--acc) 10%, transparent); }
html[data-theme="dark"] .ca-ss-item.sel{ background: color-mix(in srgb, var(--acc) 16%, transparent); }

與所有地方一樣：兩主題規則在您觸及表面顏色時適用，純宣告會勝出 —— 不需要 !important。

表單控制項與原生日期選擇器

Ask 表單輸入（.ca-form input.cain）和對話框輸入（.ca-in）是 token 樣式的 —— 表面、文字、邊框和強調焦點環均遵循主題和您的 theme_color。系統對話框（重新命名/確認）共享 Spotlight 處理：磨砂背景、呼吸式浮動效果、深色中的品牌光暈。

日曆是混合的。 在桌面（滑鼠）上，平台繪製自己的日曆 —— 完全 token 樣式，品牌色已選取日期，本地化的月/星期名稱 —— 穩定的選擇器 .ca-dp、.ca-dp-d、.ca-dp-d.sel、.ca-dp-d.today，如果品牌指南需要更多。在觸控裝置上，原生 OS 選擇器被刻意保留：移動滾輪勝過網頁中繪製的任何內容，且其面板是 OS 私有 UI，CSS 無法觸及 —— 在該處，平台控制可達到的內容（主題固定的 color-scheme、token 樣式的輸入欄位、反轉的日曆圖示），沒有更多可控制的內容。

限制您的元素選擇器範圍。 裸的 input[type="text"] { … } 為編輯器編寫，也會捕獲平台的對話框和表單欄位 —— 白色編輯器樣式滲透到深色重新命名對話框是經典症狀，且 CSS lint 現在會標記它（broad_element_selector）。改為編寫 .composer textarea 或 #input。系統對話框具有更高的優先級，因此事故不再發生 —— 但 lint 會在您依賴事故之前告訴您。

share 上也有

• input_mode —— text（預設）或 voice，會直接開啟按住說話。需要在平台上啟用語音轉文字後端。
• launcher —— 氣泡的懸停工具提示。
• theme —— 強制 light / dark，或留空以跟隨訪客的系統設定。偏好留空：小工具位於客戶頁面內部，應與之匹配。

驗證

開啟 list_shares 中的 chat_url 並查看發送按鈕。如果標籤難以閱讀，則 theme_color 未設定，且有其他內容覆蓋它 —— 檢查 custom_css 中是否有硬編碼的 color。