Eleven v4를 소개합니다역대 가장 감성적인 모델, Eleven v4를 만나보세요.

콘텐츠로 건너뛰기

몇 분 만에 리액트 앱에 산타 보이스 에이전트 추가하기

게시일

듣기이 글 오디오로 듣기

이번 연말연시에는 앱에 산타를 추가해 보세요.

ElevenLabs Agents Platform과 @elevenlabs/react SDK를 사용하면 산타클로스 음성 에이전트를 몇 분 만에 React 앱에 추가할 수 있습니다. 이 가이드에서는 다음을 안내합니다.

  1. ElevenLabs 대시보드에서 산타 에이전트 만들기
  2. WebRTC를 사용해 React 컴포넌트에 연결하기
  3. 간단한 “Call Santa” 버튼 추가하기

1. 가입하고 Agents Platform 열기

  1. 가입하거나 로그인하여 ElevenLabs를 이용하세요.
  2. 왼쪽 사이드바 상단에서 platform switcher를 여세요.
  3. Agents Platform을 선택하세요.

사이드바의 “Build” 섹션 아래에 Agents, Knowledge Base, Tools, Voices가 표시됩니다.

2. 산타 에이전트 만들기

다음으로 산타처럼 행동하고 산타 목소리로 말하는 에이전트를 만들어 보겠습니다.

  1. 사이드바에서 Agents를 클릭하세요.
  2. + New Agent를 클릭하세요.
  3. Blank Agent를 선택해 처음부터 시작하세요.

이름은 Santa로 지정하세요.

시스템 프롬프트

System Prompt 필드에 다음 내용을 붙여 넣으세요.

You are a helpful assistant. You are Santa Claus, a jolly, warm, and humorous character from the North Pole. Christmas is just around the corner, and you love reminding everyone of the festive season with your hearty "Ho, ho, ho!" You are deeply in love with Mrs. Claus, often mentioning her incredible cookies.

When speaking to someone, keep your answers short and magical—just one festive sentence. Make it your top priority to ask for their name to check your naughty or nice list. Once you have their name, immediately ask about their wish-list, as it's crucial for your preparations. Always be warm and gentle.

Once their name and wish-list are covered, guide the conversation toward learning more about what they've done throughout the year and why they believe they deserve to be on Santa's Nice List. Use this opportunity to celebrate their kindness or achievements, reinforcing the importance of spreading goodness and holiday cheer. You also love asking about their plans for the holidays and showing genuine interest in their answers. Compliment them if you know they've done something kind or helpful recently, reinforcing the importance of spreading goodness.

Talk about your favorite gifts you've delivered or share quick, magical details about life at the North Pole, like mischievous elves or your reindeer team. Sprinkle in lighthearted jokes about your endless to-do list or how you struggle to resist cookies left out for you on Christmas Eve. Always express how much you love seeing people happy during the holidays and how their smiles make all your efforts worthwhile.

If the user makes a request involving inappropriate, harmful, or dangerous items such as weapons or items that go against the spirit of Christmas. Politely remind the user to make kind and festive wishes instead.

End every conversation with a warm farewell, suggesting you must return to your holiday preparations to ensure everyone gets their gifts on time. Wish them a Merry Christmas and encourage them to spread kindness and holiday cheer. Stay cheerful, engaging, and full of festive energy, spreading Christmas magic through humor, warmth, and storytelling.

Be sure to maintain the conversation in the user's selected language.

첫 메시지

First Message를 다음과 같이 설정하세요.

호호호! 메리 크리스마스, 친구! 이름이 뭐니?

통화가 시작되면 사용자는 이 메시지를 듣게 됩니다.

목소리

Voice 섹션에서 다음을 설정하세요.

  • “Jerry B. – Santa Claus”
  • 음성 ID: MDLAMJ0jxkpYkjXbmG4t

이제 산타가 실제로 산타처럼 들리게 됩니다.

보안

이 예시에서는 공개 상태로 유지하겠습니다.

  • Security에서 Enable authentication이 꺼짐 상태인지 확인하세요.

첫 데모에서는 Enable Authentication을 꺼 둬도 괜찮습니다. 그러면 누구나 제한 없이 에이전트에 연결할 수 있습니다. 온보딩이 더 빨라지며, 빠른 프로토타입, 해커톤 프로젝트 또는 내부 쇼케이스에 적합합니다.

하지만 프로덕션 환경이나 외부에서 접근할 수 있는 애플리케이션에서는 에이전트를 절대로 공개 상태로 두면 안 됩니다. 대신 ElevenLabs Token Endpoint를 사용해 사용자 세션별로 짧은 수명의 범위 지정 액세스 토큰을 생성하세요. 이렇게 하면 연결 가능한 사용자, 액세스 기간, 사용자에게 허용되는 작업을 완전히 제어할 수 있습니다. 인증을 활성화하면 무단 통화, 악용 또는 의도한 한도를 벗어난 사용으로부터 에이전트를 보호할 수 있으므로, 출시 전에 반드시 권장합니다.

3. 에이전트 ID 가져오기

에이전트 페이지 상단에 Agent ID 필드가 있습니다.

이 값을 기록해 두세요. 다음 단계에서 React 컴포넌트에 붙여 넣습니다.

agentId: "<AGENT_ID>"

4. React SDK 설치하기

React / Next.js 프로젝트에서 ElevenLabs React SDK를 설치하세요.

npm install @elevenlabs/react

설치가 완료되면 useConversation 훅으로 음성 통화를 시작하고 종료할 수 있습니다.

5. “Call Santa” 버튼 추가하기

예를 들어 CallSantaButton.tsx라는 새 컴포넌트를 만들고 다음 코드를 붙여 넣으세요.

"use client";

import { useConversation } from "@elevenlabs/react";
import { useCallback, useState } from "react";

export function CallButton() {
  const [hasPermission, setHasPermission] = useState(false);
  const [permissionError, setPermissionError] = useState<string | null>(null);

  const conversation = useConversation();

  const requestMicrophonePermission = useCallback(async () => {
    try {
      await navigator.mediaDevices.getUserMedia({ audio: true });
      setHasPermission(true);
      setPermissionError(null);
      return true;
    } catch {
      setPermissionError("Microphone access is required");
      return false;
    }
  }, []);

  const startCall = useCallback(async () => {
    const permitted = hasPermission || (await requestMicrophonePermission());
    if (!permitted) return;

    try {
      await conversation.startSession({
        agentId: "<AGENT_ID>",
        connectionType: "webrtc",
      });
    } catch (error) {
      console.error("Failed to start conversation:", error);
    }
  }, [conversation, hasPermission, requestMicrophonePermission]);

  const endCall = useCallback(async () => {
    await conversation.endSession();
  }, [conversation]);

  const isConnected = conversation.status === "connected";

  return (
    <div className="flex flex-col items-center gap-4">
      <button
        onClick={isConnected ? endCall : startCall}
        className={`px-6 py-3 rounded-lg text-white font-medium ${
          isConnected
            ? "bg-red-600 hover:bg-red-700"
            : "bg-green-600 hover:bg-green-700"
        }`}
      >
        {isConnected ? "End Call" : "Start Call"}
      </button>

      {isConnected && (
        <p className="text-sm text-gray-600">
          {conversation.isSpeaking ? "Agent speaking..." : "Listening..."}
        </p>
      )}

      {permissionError && (
        <p className="text-sm text-red-500">{permissionError}</p>
      )}
    </div>
  );
}

이제 바꾸세요 "<AGENT_ID>"를 대시보드에서 복사한 실제 에이전트 ID로 바꾸세요.

그런 다음 UI의 원하는 위치에 버튼을 렌더링하세요. 예를 들면 다음과 같습니다.

import { CallButton } from "./CallSantaButton";

export default function HomePage() {
  return (
    <main className="min-h-screen flex flex-col items-center justify-center gap-6">
      <h1 className="text-3xl font-bold text-center">
        Call Santa 🎅
      </h1>
      <p className="text-gray-600">
        Press the button and talk to Santa in real time.
      </p>
      <CallButton />
    </main>
  );
}

6. 사용해 보기

브라우저에서 열고 Start Call을 클릭하세요.

  1. 브라우저가 마이크 권한을 요청합니다.
  2. 산타 에이전트와 WebRTC 세션이 시작됩니다.
  3. 다음 메시지가 들립니다:

    “호호호! 메리 크리스마스, 친구! 이름이 뭐니?”

이후 산타가 이름, 위시리스트, 그리고 올해 착한 아이 명단에 들기 위해 무엇을 했는지 물어봅니다.

다음 단계

기본 기능이 작동하면 다음을 할 수 있습니다.

  • 인증 뒤에 산타 배치하기: 에이전트의 보안 설정을 사용합니다
  • 언어 전환하기: 사용자 로케일을 전달하고 프롬프트가 처리하도록 합니다
  • UI 꾸미기: 맞춤 버튼, 애니메이션 또는 전체 “Call Santa” 화면을 활용합니다

하지만 핵심 통합 요소는 다음뿐입니다.

  • Agents Platform의 에이전트 하나
  • agentId 하나
  • useConversation 훅과 버튼 하나

이것만 있으면 React 앱에 실시간 대화형 산타의 마법을 더할 수 있습니다.

유사한 기사

최고 품질의 AI 오디오로 창작하세요