배포웹

위젯 맞춤 설정

브랜드에 맞게 위젯 모양을 맞춤 설정하고 HTML에서 에이전트의 동작을 개인화하는 방법을 알아보세요.

위젯을 사용하면 모든 웹사이트에 ElevenAgents를 즉시 통합할 수 있습니다. UI에서 위젯을 맞춤 설정하거나, 스타일과 동작을 완전히 제어할 수 있는 타입 안전 ElevenAgents SDK를 사용할 수 있습니다. SDK 재정의는 UI 맞춤 설정보다 우선 적용됩니다. 위젯은 멀티모달을 지원하며 텍스트와 오디오를 모두 처리할 수 있습니다.

호스팅 MCP 서버를 통해 Claude 또는 다른 MCP 클라이언트에서 에이전트의 위젯 구성과 공유 가능한 링크를 가져올 수도 있습니다.

모달리티 구성

위젯은 사용 사례에 맞출 수 있는 유연한 입력 모드를 지원합니다. 대시보드에서 채널 → 위젯 → 인터페이스 아래에서 이 옵션을 구성하세요.

멀티모달 기능은 클라이언트 SDK에서 완전히 지원됩니다. 자세한 내용은 여기에서 확인하세요.

위젯 인터페이스 옵션

사용 가능한 모드:

  • 음성 전용(기본값): 사용자는 음성으로만 상호작용합니다.
  • 음성 + 텍스트: 사용자는 대화 중 음성 입력과 텍스트 입력 간에 전환할 수 있습니다.
  • 채팅 모드: 텍스트 메시지로 시작하면 음성 기능 없이 채팅(텍스트 전용) 모드로 대화가 시작됩니다.

SDK를 통해 채팅(텍스트 전용) 모드를 사용하는 방법은 채팅 모드 가이드를 참조하세요.

위젯은 기본적으로 음성 전용 모드입니다. 멀티모달 상호작용을 허용하려면 텍스트 입력 토글을 활성화하고, 텍스트로 시작하는 순수 텍스트 기반 대화를 지원하려면 텍스트 전용 모드 지원을 활성화하세요.

위젯 삽입

현재 위젯에는 인증이 비활성화된 공개 에이전트가 필요합니다. 에이전트 설정의 고급 탭에서 인증이 비활성화되어 있는지 확인하세요.

이 코드 스니펫을 웹사이트의 <body> 섹션에 추가하세요. 사이트 전체에서 사용할 수 있도록 기본 index.html 파일에 배치하세요.

위젯 삽입 코드
<elevenlabs-convai agent-id="<replace-with-agent_7101k5zvyjhmfg983brhmhkd98n6>"></elevenlabs-convai>
<script
  src="https://unpkg.com/@elevenlabs/convai-widget-embed"
  async
  type="text/javascript"
></script>

보안을 강화하려면 에이전트의 허용 목록(보안 탭에 있음)에서 허용된 도메인을 정의하세요. 이렇게 하면 지정된 호스트로만 액세스가 제한됩니다.

위젯 속성

이 기본 삽입 코드는 에이전트 대시보드에 정의된 기본 구성으로 위젯을 표시합니다. 위젯은 추가 맞춤 설정을 위한 다양한 HTML 속성을 지원합니다.

<elevenlabs-convai
  agent-id="agent_id"              // Required: Your agent ID
  signed-url="signed_url"          // Alternative to agent-id
  server-location="us"             // Optional: "us" or default
  variant="expanded"               // Optional: Widget display mode
  dismissible="true"               // Optional: Allow the user to minimize the widget
></elevenlabs-convai>
<elevenlabs-convai
  avatar-image-url="https://..." // Optional: Custom avatar image
  avatar-orb-color-1="#6DB035" // Optional: Orb gradient color 1
  avatar-orb-color-2="#F5CABB" // Optional: Orb gradient color 2
></elevenlabs-convai>
<elevenlabs-convai
  action-text="Need assistance?" // Optional: CTA button text
  start-call-text="Begin conversation" // Optional: Start call button
  end-call-text="End call" // Optional: End call button
  expand-text="Open chat" // Optional: Expand widget text
  listening-text="Listening..." // Optional: Listening state
  speaking-text="Assistant speaking" // Optional: Speaking state
></elevenlabs-convai>

위젯은 에이전트 응답의 Markdown을 렌더링합니다. 피싱을 방지하기 위해 링크는 기본적으로 일반 텍스트로 표시됩니다.

<elevenlabs-convai
  markdown-link-allowed-hosts="example.com"  // Domains where links are clickable (use "*" for all)
  markdown-link-include-www="true"           // Also allow www variants (default: true)
  markdown-link-allow-http="true"            // Allow http:// links (default: true)
  syntax-highlight-theme="dark"              // Code block theme: "dark", "light", or "auto"
></elevenlabs-convai>

런타임 구성

런타임에 에이전트의 동작을 맞춤 설정하는 데 HTML 속성 2개를 더 사용할 수 있습니다. 이 두 기능은 함께 또는 각각 사용하거나, 전혀 사용하지 않을 수 있습니다.

동적 변수

동적 변수를 사용하면 런타임 값을 에이전트의 메시지, 시스템 프롬프트 및 도구에 삽입할 수 있습니다.

<elevenlabs-convai
  agent-id="agent_7101k5zvyjhmfg983brhmhkd98n6"
  dynamic-variables='{"user_name": "John", "account_type": "premium"}'
></elevenlabs-convai>

에이전트에 필요한 모든 동적 변수는 위젯에서 전달해야 합니다.

자세한 내용은 동적 변수 가이드를 참조하세요.

재정의

재정의를 사용하면 런타임에 에이전트의 동작을 완전히 맞춤 설정할 수 있습니다.

<elevenlabs-convai
  agent-id="agent_7101k5zvyjhmfg983brhmhkd98n6"
  override-language="es"
  override-prompt="Custom system prompt for this user"
  override-first-message="Hi! How can I help you today?"
  override-voice-id="axXgspJ2msm3clMCkdW3"
></elevenlabs-convai>

특정 필드에 대해 재정의를 활성화할 수 있으며, 이는 전적으로 선택 사항입니다.

자세한 내용은 재정의 가이드를 참조하세요.

시각적 맞춤 설정

위젯의 모양, 텍스트 콘텐츠, 언어 선택 등을 맞춤 설정하세요.

대시보드에서 에이전트를 열고 위젯 탭으로 이동하여 모양, 아바타, 텍스트, 약관, 언어 지원 등을 맞춤 설정하세요.

위젯 맞춤 설정

브랜드 아이덴티티에 맞게 위젯의 색상과 형태를 맞춤 설정하세요.

위젯 모양

고급 구현

더 고급 맞춤 설정을 하려면 Next.js, React 또는 Python 애플리케이션에서 타입 안전 ElevenAgents SDK를 사용해야 합니다.

클라이언트 도구

클라이언트 도구를 사용하면 이벤트 리스너를 추가하여 위젯 기능을 확장할 수 있습니다. 이를 통해 위젯은 다음과 같은 작업을 수행할 수 있습니다.

  • 사용자를 특정 페이지로 리디렉션
  • 지원 팀에 이메일 전송
  • 사용자를 외부 URL로 리디렉션

이러한 도구의 작동 예를 보려면 이 페이지 오른쪽 하단에서 에이전트와 통화를 시작하세요. 참고용으로 소스 코드는 GitHub에서 확인할 수 있습니다.

클라이언트 도구 만들기

첫 번째 클라이언트 도구를 만들려면 클라이언트 도구 가이드를 따르세요.

클라이언트 도구 구성

구현 예시

다음은 JavaScript 코드에서 위젯이 트리거한 redirectToExternalURL 도구를 처리하는 방법의 예시입니다.

index.js
document.addEventListener("DOMContentLoaded", () => {
  const widget = document.querySelector("elevenlabs-convai");
  if (widget) {
    // Listen for the widget's "call" event to trigger client-side tools
    widget.addEventListener("elevenlabs-convai:call", (event) => {
      event.detail.config.clientTools = {
        // Note: To use this example, the client tool called "redirectToExternalURL" (case-sensitive) must have been created with the configuration defined above.
        redirectToExternalURL: ({ url }) => {
          window.open(url, "_blank", "noopener,noreferrer");
        },
      };
    });
  }
});

React, Next.js 및 Python 구현을 위한 타입 안전 SDK를 살펴보세요.