위젯 맞춤설정

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

모달리티 구성

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

사용 가능한 모드:

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

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>

<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>

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

시각적 맞춤설정

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

리치 콘텐츠

리치 콘텐츠를 사용하면 에이전트가 메시지와 함께 대화형 구성 요소로 응답할 수 있습니다. 대시보드의 채널 → 위젯 → 리치 콘텐츠에서 구성하세요.

리치 콘텐츠는 텍스트 대화에서 표시되며, 인터페이스에서 대화의 실시간 트랜스크립트가 활성화된 경우 음성 대화에서도 표시됩니다. 임베디드 위젯에서만 사용할 수 있습니다.

에이전트가 리치 콘텐츠를 사용하는 방식

첫 메시지 답장을 제외하면, 에이전트는 매 차례 빠른 답장 또는 캐러셀을 표시할지 결정합니다. 구성 요소가 필요하지 않은 답장은 일반 텍스트로 유지됩니다. 표시 시점과 방식을 설정하려면 에이전트의 시스템 프롬프트에 설명하세요.

새 에이전트에서는 빠른 답장과 캐러셀이 기본으로 활성화됩니다. 리치 콘텐츠를 사용할 수 있기 전에 생성된 에이전트의 경우 위젯 설정에서 활성화하세요.

고급 구현

클라이언트 도구

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

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

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

클라이언트 도구 만들기

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

구현 예시

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

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