채팅에 브랜드 적용 — 색상 및 로고

원칙 — 팔레트가 아닌 단색을 사용하세요. 배경색은 저장 시 파생되므로 모든 조합이 가독성을 유지합니다. 텍스트 색상을 직접 선택하면 가독성이 떨어지는 버튼을 배포하게 됩니다.

브랜딩은 에이전트가 아닌 **공유(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")

이름을 변경하기 위해 새 공유를 생성하고 기존 공유를 삭제할 필요가 없습니다. 새 공유는 새 토큰을 생성하므로 고객 사이트에 이미 임베드된 링크가 작동하지 않게 됩니다. 표시된 이름과 주소는 동일한 것이 아니며, 런칭 후에는 둘 중 하나만 안전하게 변경할 수 있습니다.

두 번째 색상: 브랜드에 두 번째 색상이 있는 경우에만

대부분의 브랜드는 단색을 가지며 여기서 추가 설정이 필요하지 않습니다. 일부 브랜드는 주요 색상과 강조 색상을 가집니다. 두 번째 색상을 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=""로 지우면 파생된 값도 삭제되며 위젯이 기본 파란색으로 돌아갑니다. 설정하지 않아도 동일한 효과가 발생하며, 내장된 토큰은 이미 매칭된 쌍입니다.

로고: 종횡비가 사용처를 결정합니다

절대 URL을 전달하세요. 로고는 서로 다른 제약 조건을 가진 두 곳에 표시됩니다.

• 헤더 바 — 높이에 맞춰지고 너비는 자유롭습니다. 넓은 워드마크를 포함하여 모든 종횡비가 작동합니다.
• 축소된 말풍선 — 정사각형입니다. 로고가 말풍선의 모양이기 때문입니다. 0.74에서 1.35 사이의 비율만 여기에 사용되며, 넓은 워드마크는 가독성이 떨어지는 스트립으로 찌그러지는 대신 플랫폼 아이콘으로 대체됩니다.

따라서 넓은 워드마크의 경우 실용적인 해결책은 두 개의 파일입니다. 헤더용 워드마크와 말풍선용 정사각형 마크입니다. 고객에게 워드마크만 있는 경우 헤더에는 브랜드가 표시되고 말풍선에는 중립적인 아이콘이 표시됩니다. 읽을 수 없는 조각보다는 낫습니다.

워드마크를 정사각형으로 자르지 마세요. 자르면 단어의 절반만 남게 되어 더 이상 그들의 상표가 아닙니다.

브랜드 가이드가 모든 것을 재정의하는 경우

일부 고객은 라이트/다크 테마 모두에서 우리의 팔레트를 따르지 않는 엄격한 팔레트를 가지고 있습니다. custom_css는 브랜드 변수 이후에 삽입되므로 일반 선언만으로도 승리합니다. !important가 필요하지 않습니다. (과거에는 인라인 스타일로 색상이 설정되었으므로 필요했습니다. 더 이상 그렇지 않습니다.)

⚠️ CSS를 작성하기 전에 반드시 읽으세요

두 개의 블록을 작성해야 합니다. 라이트용 :root와 다크용 html[data-theme="dark"]입니다.

:root는 두 테마 모두에서 일치하며 플랫폼의 다크 규칙보다 우선순위가 높습니다(동일한 특이도이며 귀하의 코드가 나중에 오기 때문). 따라서 :root 아래에만 팔레트를 작성하면 방문자의 라이트/다크 토글이 아무런 변화도 일으키지 않습니다. data-theme가 전환되지만 그 뒤에 따르는 변수가 없습니다.

이는 이미 프로덕션에서 발생했습니다. 에이전트가 :root 아래에 전체 다크 팔레트를 넣었고 페이지는 멋지게 보였으며 테마 버튼은 몇 주 동안 아무도 눈치채지 못한 죽은 컨트롤이 되었습니다. 페이지가 올바르게 보이므로 이것이 보고되지 않는 이유입니다.

고객이 실제로 하나의 테마만 원하는 경우 대신 공유의 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에서 파생되며(22%/55% 알파의 color-mix를 통해) 브랜드 색상으로 자동으로 펄스합니다. 의도적으로 다른 처리를 위해 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를 재정의하고 흰색 텍스트를 그대로 두는 것입니다. 질문 양식 버튼은 1.8:1의 노란색-흰색 텍스트가 되어 고객이 "다크 모드에서 양식 버튼이 읽을 수 없다"고 보고합니다. custom_css에서 --acc를 재정의하는 경우 동일한 블록, 두 테마 모두에서 --acc-fg를 관리해야 합니다. 또는 더 나은 방법은 CSS를 사용하지 않고 theme_color를 설정하여 플랫폼이 준수하는 --acc-fg를 파생하게 하는 것입니다.

채팅 설치 가능하게 만들기 (PWA)

독립형 채팅 페이지(/s/… 링크, QR 코드 및 아래 별칭 URL)는 설치 가능한 앱입니다. 방문자는 고유한 아이콘과 이름으로 홈 화면에 추가할 수 있습니다. 두 가지 노브는 에이전트별로 구성됩니다. 홈 화면에 설치되는 것은 하나의 에이전트 진입 페이지이므로 각 에이전트는 고유한 아이콘을 가진 자체 앱입니다(지원 에이전트와 영업 전 에이전트는 서로 다른 앱으로 설치됨):

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는 초대를 비활성화합니다. 닫기는 방문자별로 기억됩니다.
• 아이콘은 선택 사항입니다. 아이콘이 없으면 플랫폼 아이콘이 사용됩니다. 에이전트 이름만으로 호출하여 해당 에이전트의 현재 구성을 읽을 수 있습니다.

사람에게 건네는 링크

테넌트 별칭 및 에이전트 별칭이 모두 설정된 경우, create_share / list_shares는 pretty_url을 반환합니다 — https://chat.agent4.io/t/<테넌트-별칭>/<에이전트-별칭>. 이 링크를 사람들에게 제공하고 자료에 인쇄하세요. 읽기 쉽고 기억하기 쉬우며 토큰 회전 시에도 유지됩니다(플랫폼은 그 뒤에 공유를 지연 유지합니다). /s/<토큰> 형식은 임베드 및 기계를 위해 유지됩니다.

응답에 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는 활성을 의미합니다 — 첫 방문 시 인증서가 발급됩니다.

워크스페이스당 하나의 도메인. agent_alias를 비워두면 테넌트의 브랜드 페이지로 이동합니다. 하나의 에이전트 채팅으로 직접 이동하도록 설정하세요. 기존 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 불필요.

양식 컨트롤 및 네이티브 날짜 선택기

질문 양식 입력(.ca-form input.cain) 및 대화 상자 입력(.ca-in)은 토큰 스타일이 적용됩니다 — 표면, 텍스트, 테두리 및 강조 포커스 링은 모두 테마 및 theme_color를 따릅니다. 시스템 대화 상자(이름 변경/확인)는 Spotlight 처리를 공유합니다: 서리 낀 배경, 숨 쉬는 입체감, 다크 모드에서의 브랜드 글로우.

캘린더는 하이브리드입니다. 데스크톱(마우스)에서 플랫폼은 자체 캘린더를 그립니다 — 완전히 토큰 스타일, 브랜드 색상으로 선택된 날짜, 현지화된 월/요일 이름 — 브랜드 가이드에서 더 많은 것이 필요한 경우 안정적인 선택기 .ca-dp, .ca-dp-d, .ca-dp-d.sel, .ca-dp-d.today. 터치 장치에서는 네이티브 OS 선택기가 의도적으로 유지됩니다. 모바일 휠은 웹 페이지에서 그려진 anything보다 뛰어나며, 그 패널은 CSS로 접근할 수 없는 OS 프라이빗 UI입니다 — 여기서 플랫폼은 도달 가능한 것만 제어합니다(테마 고정 color-scheme, 토큰 스타일 입력 필드, 반전된 캘린더 아이콘) 및 더 이상 제어할 것이 없습니다.

선택기의 범위를 지정하세요. .composer textarea 또는 #input 대신 작성한 순수 input[type="text"] { … }는 플랫폼의 대화 상자와 양식 필드도 포착합니다 — 어두운 이름 변경 대화 상자에 흰색 컴포저 스타일이 새어드는 것이 고전적인 증상이며, CSS 린트는 이를 이제 플래그합니다(broad_element_selector). 시스템 대화 상자는 더 높은 특이도에 위치하므로 사고가 발생하지 않지만 — 린트는 사고에 의존하기 전에 알려줍니다.

공유에서도

• input_mode — text(기본값) 또는 voice, 대화 유지 모드로 바로 엽니다. 플랫폼에서 음성 인식 백엔드가 활성화되어야 합니다.
• launcher — 말풍선의 호버 툴팁.
• theme — light / dark로 강제하거나 방문자의 시스템 설정을 따르도록 비워두세요. 비워두기를 선호하세요: 위젯은 고객의 페이지 내부에 위치하며 그에 맞춰야 합니다.

확인

list_shares에서 chat_url을 열고 전송 버튼을 확인하세요. 레이블이 읽기 어려운 경우 theme_color가 설정되지 않았거나 이를 재정의하는 무언가가 있습니다 — custom_css에서 하드코딩된 color를 확인하세요.