チャットにブランドを適用する — 色とロゴ

原則 — パレットではなく、1つの色を渡す。 フォアグラウンドの色は保存時にこの色から派生するため、すべての組み合わせで読みやすさが保たれます。独自のテキスト色を選択すると、誰も読めないボタンが納品されてしまいます。

ブランディングはエージェントではなく**共有（share）**に宿ります：同じエージェントが、あるサイトではホワイトラベルウィジェットとして、別の場所では単なるリンクとして機能します。そのため、まずトークンを取得してください。

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",
)

渡したフィールドのみが変更され、設定の残りはそのまま維持されます。

共有の名前変更

label はチャットページの上部に表示される名前、およびブラウザタブのタイトルです。これは他のフィールドと同様に configure_share のフィールドです：

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

名前を変更するために、置き換え用の共有を作成して古い共有を削除する必要はありません。 新しい共有を作成すると新しいトークンが生成され、顧客のサイトに既に埋め込まれているリンクが無効になります — 表示される名前とアドレスは同じものではなく、公開後に安全に変更できるのはそのうち1つだけです。

2つ目の色：ブランドに2つ目の色がある場合のみ

ほとんどのブランドは1つの色しか持たず、ここでの設定は不要です。一部にはプライマリーとハイライトの2色があります — 2つ目の色を 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 から our component classes を上書きすることは できます が、後悔することになります：これらのクラス名は内部実装であり、変更されます。変更されると、ブランディングは静かに壊れます。2つの色を設定し、各色がどこに属するかをコンポーネントに任せてください。

色：1つを渡せば4つが得られる

theme_color はブランドのプライマリー色で、#RGB または #RRGGBB 形式です。保存時にプラットフォームはWCAGコントラストに基づいてフォアグラウンドを派生させ、保存します：

明るいブランド色の場合、白ではなく暗いテキストが使用されます。#F7B331 に白テキストを当てるとコントラスト比は1.83:1となり、UIコンポーネントの最低基準である3:1を下回ります — つまりラベルは本当に読めません。派生した暗いフォアグラウンドは10.21:1を計測します。

パレットを自分で計算したり、テキスト色を設定しようとしたりしないでください — これらはサーバーで派生しており、あなたの値は上書きされます。1つの色を渡すことが、すべての作業です。

これをクリアする（theme_color=""）と、派生値も削除され、ウィジェットはデフォルトの青に戻ります。未設定のままにしても同じ結果になります — 組み込みのトークンはすでにマッチしたペアです。

ロゴ：アスペクト比が使用箇所を決定する

絶対URLを渡してください。ロゴは異なる制約を持つ2箇所で表示されます：

• ヘッダーバー — 高さに合わせて配置され、幅は自由です。ワイドなワードマークを含む、あらゆるアスペクト比が機能します。
• 折りたたみ済みバブル — 正方形です。ロゴはバブルの形状そのものであるため、0.74から1.35の間のアスペクト比のみがここで使用されます。ワイドなワードマークは、読み取れないほど小さな帯に押し込められるのではなく、プラットフォームのアイコンにフォールバックします。

したがって、ワイドなワードマークの場合、実用的な答えは2つのファイルです：ヘッダー用のワードマーク、バブル用の正方形マーク。顧客にワードマークしかない場合、ヘッダーにはブランドが表示され、バブルにはニュートラルなアイコンが表示されます — 読めない細切れにするよりもマシです。

ワードマークを正方形に切り抜かないでください。切り抜くとワードの半分が残ることになり、それはもう彼らの商標ではありません。

ブランドガイドがすべてを上書きする場合

一部の顧客は、どちらのテーマでも ours に従わない厳格なパレットを持っています。custom_css はブランド変数の後に注入されるため、単純な宣言ですでに優先されます — !important は不要です。（以前は必要でした。色がインラインスタイルとして設定されていたためです。もうそうではありません。）

⚠️ CSSを記述する前にこれを読んでください

2つのブロックを記述する必要があります：：root はライト用、html[data-theme="dark"] はダーク用です。

：root は両方のテーマで一致し、プラットフォームのダークルールより優先されます（同じ特異性で、 yours は後から適用されます）。したがって、：root の下にのみパレットを記述すると、訪問者のライト/ダーク切替は何も変更しません — data-theme は切り替わりますが、それに続く変数はありません。

これは実際に本番環境で発生しました：あるエージェントが ：root の下に完全なダークパレットを配置し、ページは見事に見え、テーマボタンは数週間誰も気づかない死んだコントロールになりました。ページは正しく見えるため、これが報告されないのです。

顧客が本当に1つのテーマのみを望んでいる場合、共有の 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 はブランド色であり、通常は両方で同じですが、例では暗いテーマで明るくしています。これは、ほぼ黒の背景に深い紫を置くと見えにくいためです。

覚えておくべきことがもう2つあります：

• 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コード、および以下のエイリアスURL）はインストール可能なアプリです：訪問者はホーム画面に追加でき、独自のアイコンと名前を使用できます。2つのノブ、エージェントごとに設定 — ホーム画面にインストールされるのは1つのエージェントのエントリページであり、各エージェントは独自のアイコンを持つ独自のアプリとしてインストールされます（サポートエージェントとプリセールスエージェントは、2つの異なるアプリとしてインストールされます）：

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
)

• マスター画像は1回取得され、プラットフォームはセット全体を生成します — ブラウザタブのファビコン、192/512のインストールアイコン、Androidのマスク可能バリアント。正方形でないマスターは中央切り抜きされるため、ワイドなワードマークではなく、正方形のマークを使用してください。
• install_prompt は訪問者がチャットページで何を見るかを制御します：banner は消せる細いバーです（Android/Chromeはシステムインストールダイアログをトリガーします；iOSは「共有 → ホーム画面に追加」のウォークスルーが表示されます。AppleはAPIを提供していないため）、card はより目立つ初回訪問カード、off は招待を無効にします。消去は訪問者ごとに記憶されます。
• アイコンはオプションです — 指定しない場合、プラットフォームのアイコンが使用されます。エージェント名のみで呼び出すと、そのエージェントの現在の設定が読み取られます。

人間に渡すリンク

テナントエイリアスとエージェントエイリアスの両方が設定されている場合、create_share / list_shares は pretty_url を返します — https://chat.agent4.io/t/<tenant-alias>/<agent-alias>。これが人々に渡すリンクであり、資料に印刷すべきものです：読みやすく、覚えやすく、トークンのローテーション後も生存します（プラットフォームは背後で共有を遅延維持します）。/s/<token> 形式は埋め込みとマシン用に残されています。

レスポンスに pretty_url がない場合？エイリアスが設定されていない — トークンリンクを納品するのではなく、それを修正してください：エージェントエイリアスは create_agent(alias=…) または PUT /agents/{name}/alias 経由、テナントエイリアスはコンソール → 設定にあります。エージェントのエイリアス設定自体が公開アクションです：エイリアスページは初回訪問時に匿名共有を自動作成します。

顧客の独自ドメイン

ホストされたチャットページは顧客のドメインで提供できます — 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_target（endpoint.agent4.io）にサブドメインからCNAMEを追加するよう指示します。サブドメインのみ — アペックスドメイン（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 はライブを意味します — 初回訪問時に証明書が発行されます。

ワークスペースあたり1つのドメイン。agent_alias を空にするとテナントのブランドページに着地します；1つのエージェントのチャットに直接着地させるために設定してください。既存の 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); }

どこでもと同様：表面色に触れた瞬間に2テーマルールが適用され、単純な宣言が勝ちます — !important は不要です。

フォームコントロールとネイティブ日付ピッカー

Askフォーム入力（.ca-form input.cain）とダイアログ入力（.ca-in）はトークンスタイルです — 表面、テキスト、ボーダー、アクセントフォーカスリングはすべてテーマとあなたの theme_color に従います。システムダイアログ（名前変更/確認）はSpotlightの処理を共有します：フロストバックドロップ、呼吸するエレベーション、ダークでのブランドグロー。

カレンダーはハイブリッドです。 デスクトップ（マウス）では、プラットフォームは独自のカレンダーを描画します — 完全にトークンスタイル、ブランド色の選択済み日、ローカライズされた月/曜日名 — 安定したセレクター .ca-dp、.ca-dp-d、.ca-dp-d.sel、.ca-dp-d.today は、ブランドガイドでさらに必要な場合に使用します。タッチデバイスでは、ネイティブOSピッカーが意図的に維持されます：モバイルのホイールはウェブページで描画された anything より優れており、そのパネルはOSプライベートUIでありCSSでは到達できません — ここではプラットフォームが到達可能なものを制御します（テーマ固定の color-scheme、トークンスタイルの入力フィールド、反転したカレンダーアイコン）それ以上制御できるものは存在しません。

要素セレクターをスコープしてください。 裸の input[type="text"] { … } は、コンポーザ用に記述しても、プラットフォームのダイアログとフォームフィールドもキャプチャします — 暗い名前変更ダイアログに白いコンポーザスタイルが漏れ出すのは古典的な症状であり、CSSリントはこれをフラグ付けします（broad_element_selector）。.composer textarea または #input を代わりに記述してください。システムダイアログはより高い特異性を持つため、事故は発生しませんが — リントは、事故に依存する前に警告します。

共有上でも

• input_mode — text（デフォルト）または voice。これはホールドトゥートークに直接開きます。プラットフォームで音声認識バックエンドが有効になっている必要があります。
• launcher — バブルのホバーツールチップ。
• theme — light / dark を強制するか、訪問者のシステム設定に従うために空のままにします。空を優先：ウィジェットは顧客のページ内にあり、それに一致すべきです。

検証

list_shares から chat_url を開き、送信ボタンを見てください。ラベルが読みづらい場合、theme_color が設定されていないか、それを上書きするものが存在します — custom_css でハードコードされた color を確認してください。