Wixzel Voice로 웹사이트에 말하는 AI 마스코트 추가하기

시작하기 전에 무엇이 필요한가요?

• 크레딧이 있는 Wixzel Voice 계정. 위젯 통화는 무료 테스트 시간이 아니라 실제 크레딧으로 결제되며, 최소 충전 금액은 $5입니다.
• agents:write와 calls:write 스코프가 있는 API 키(서버에 보관). 아래 작업은 모두 콘솔의 에이전트 마스코트 탭에서도 할 수 있습니다.
• script 태그를 추가할 수 있고 HTTPS로 제공되는 웹사이트. 브라우저는 HTTPS 페이지에만 마이크를 허용합니다.

Wixzel Voice에서 단계별로 어떻게 만드나요?

1. 01웹사이트로 에이전트 만들기

   사이트 주소와 역할을 넘깁니다. role은 receptionist, support, sales, guide 중 하나이거나 직접 쓴 설명입니다.

   shell복사

   curl https://api.voice.wixzel.com/v1/agents/generate \
     -H "Authorization: Bearer $WIXZEL_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{ "website_url": "https://smiledental.example", "role": "receptionist" }'

   make-agent.mjs (TypeScript SDK)복사

   import { WixzelVoice, waitForAgent } from 'wixzel-voice';
   
   const client = new WixzelVoice({ apiKey: process.env.WIXZEL_API_KEY });
   
   let agent = await client.agents.generate({
     website_url: 'https://smiledental.example',
     role: 'receptionist',
   });
   agent = await waitForAgent(client.agents, agent); // until the mascot is ready or failed
   console.log(agent.id, agent.name, agent.mascot.status, agent.knowledge_base_id);

   즉시 대화할 수 있는 에이전트와 mascot.status: "building"으로 응답합니다. 백그라운드에서 페이지를 읽고, 프롬프트와 첫 인사를 쓰고, 읽은 내용으로 지식 베이스를 만들고, 브랜드 색상으로 마스코트를 그립니다. mascot.status가 ready가 될 때까지 GET /v1/agents/{id}를 폴링하십시오. 보통 1분이 걸리지 않습니다. SDK에서는 waitForAgent가 폴링을 대신합니다. 생성에 실패해도 에이전트는 기존 모습 그대로 동작합니다.

   에이전트는 Gemini Live로 시작합니다. 엔진, 음성, 프롬프트는 다른 에이전트처럼 PATCH /v1/agents/{id}로 바꿀 수 있으며, 마스코트는 그대로 유지됩니다.

2. 02위젯을 켜고 통화할 수 있는 사람 정하기

   공유는 직접 켜기 전까지 꺼져 있습니다. 사이트가 제공되는 오리진을 나열하십시오. 위젯은 그 외의 곳에서는 통화를 시작하지 않습니다.

   shell복사

   curl -X PATCH https://api.voice.wixzel.com/v1/agents/AGENT_ID/mascot \
     -H "Authorization: Bearer $WIXZEL_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "welcome_message": "Hi! I am Molly from Smile Dental. Tap Call to talk to me.",
       "sharing": {
         "embed": true,
         "embed_origins": ["https://smiledental.example", "https://www.smiledental.example"],
         "caller_info": "contact",
         "max_call_seconds": 300,
         "daily_minutes": 60,
         "calls_per_visitor_daily": 3,
         "max_concurrent_calls": 2
       }
     }'

   caller_info는 방문자가 통화 전에 제공하는 정보입니다. none(기본값)은 아무것도 묻지 않고, contact는 이름과 전화번호 또는 이메일을 묻고, google은 Google 로그인을 요청합니다. Google 로그인으로 상대가 누구인지 알 수 있으며, 방문자에게 Wixzel 계정이 만들어지지는 않습니다. 사용자 사이트에서는 voice.wixzel.com의 작은 창으로 열리며, 결과는 embed_origins에 있는 오리진에만 전달됩니다.

   네 가지 한도로 공개 통화를 예산 안에 둡니다. 통화 1건의 최대 길이, 모든 방문자를 합친 하루 공개 통화 시간(UTC 자정까지), 방문자 1명의 하루 통화 횟수, 동시 통화 수입니다. 위의 값이 기본값입니다. "link": true를 추가하면 voice.wixzel.com/m?id=… 공유 페이지도 생깁니다.

   응답에는 m_4fT9qLx2Bv8K 같은 mascot.public_id가 들어 있습니다. script 태그에 넣는 ID입니다.

3. 03script 태그 하나 붙여 넣기

   마스코트를 보여 줄 모든 페이지의 닫는 body 태그 앞에 다음을 추가합니다.

   index.html복사

   <script src="https://voice.wixzel.com/embed.js" data-mascot="m_4fT9qLx2Bv8K" async></script>

   마스코트는 환영 메시지와 함께 오른쪽 아래 구석에서 기다립니다. 방문자가 Call 버튼을 누르고 마이크를 허용한 뒤 말하면, 마스코트가 듣고, 생각하고, 에이전트 음성에 맞춰 입을 움직입니다. 위젯은 shadow root 안에서 실행되므로 사이트 CSS와 위젯 CSS가 서로 영향을 주지 않습니다.

4. 04위치를 직접 정하고, 에이전트가 페이지에서 동작하게 하기

   구석이 아니라 원하는 요소 안에 표시하려면 태그에서 data-mascot을 빼고, 스크립트가 로드된 뒤 WixzelMascot.mount를 호출합니다.

   클라이언트 도구는 에이전트가 요청할 때 페이지에서 실행됩니다. 예를 들어 예약 페이지를 여는 식입니다. 콘솔이나 POST /v1/tools로 에이전트용 도구를 만든 뒤, 스크립트 로드 전이나 후에 동작을 등록합니다.

   index.html복사

   <div id="talk"></div>
   <script>
     window.WixzelMascot = Object.assign(window.WixzelMascot || {}, {
       tools: {
         open_page: ({ path }) => {
           location.href = path;
           return { opened: path };
         },
       },
     });
   </script>
   <script
     src="https://voice.wixzel.com/embed.js"
     async
     onload="WixzelMascot.mount(document.getElementById('talk'), { mascot: 'm_4fT9qLx2Bv8K' })"
   ></script>

   핸들러가 반환한 값은 에이전트에게 돌아가고, 에이전트가 발신자에게 알려 줍니다. 서버를 호출하는 웹훅 도구도 위젯에서 동작합니다.

5. 05통화한 사람 확인하고 차단하기

   위젯 통화마다 발신자가 기록됩니다. 에이전트의 발신자 목록을 조회합니다.

   shell복사

   curl "https://api.voice.wixzel.com/v1/callers?agent_id=AGENT_ID&limit=20" \
     -H "Authorization: Bearer $WIXZEL_API_KEY"
   
   curl -X PATCH https://api.voice.wixzel.com/v1/callers/CALLER_ID \
     -H "Authorization: Bearer $WIXZEL_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{ "blocked": true }'

   각 발신자에는 대략적인 location(IP 주소로 추정한 도시, 지역, 국가. IP 주소는 해시로만 보관), platform(브라우저, 운영체제, 기기), 통화한 페이지의 page_url, 방문자가 제공한 정보, call_count가 있습니다. 브라우저가 보관하는 임의의 ID로 한 사람의 통화를 묶으며, 핑거프린팅은 하지 않고, 위젯은 어떤 정보가 공유되는지 발신자에게 알립니다.

   차단된 발신자는 위젯, 공유 링크, 앱, 전화 어디에서도 그 에이전트에 다시 통화할 수 없습니다. 각 통화는 대화 기록, 비용과 함께 GET /v1/calls에도 있으며 caller_id로 필터링할 수 있습니다.

Wixzel Voice에서 이 빌드의 비용은 얼마인가요?

이 빌드에는 Wixzel Voice의 어떤 한도가 적용되나요?

• 오디오는 전화 수준인 양방향 8 kHz G.711 µ-law입니다.
• 위젯은 embed_origins에 있는 오리진(최대 20개)에서만 통화를 시작합니다.
• 공개 통화는 에이전트에 설정한 한도 안에서만 이루어집니다. daily_minutes를 넘으면 UTC 자정까지 통화가 거부됩니다.
• 위젯 통화는 전화 통화, 앱 세션과 함께 계정의 동시 통화 한도(기본 5건)에 포함됩니다. max_concurrent_calls로 붐비는 페이지 하나가 한도를 모두 차지하지 않게 합니다.
• 위젯 통화는 실제 크레딧을 사용합니다. 무료 테스트 시간은 콘솔에서 자신의 에이전트와 대화할 때 쓰는 것입니다.
• 웹 통화에서는 상담원 연결이 되지 않습니다. 연결에는 전화 회선이 필요합니다.