Voximplant

에이전트 생성 또는 선택

ElevenAgents에서 에이전트를 생성하세요. 통화가 연결되는 즉시 말해야 한다면 첫 메시지를 지정하세요. 오디오 형식은 통합에서 설정하므로 에이전트에 구성된 형식은 Voximplant 통화에 사용되지 않습니다.

통화 종료 활성화

에이전트 → 도구 → 시스템 도구에서 통화 종료를 활성화하여 에이전트가 대화를 끝낼 수 있게 하세요. 에이전트가 통화를 종료할 때 제공하는 사유는 결정과 함께 시나리오로 전송됩니다.

Voximplant 전환 규칙 추가(선택 사항)

에이전트가 발신자를 상담원에게 연결할 수 있게 하려면, provider 구성이 voximplant인 전환 규칙과 함께 번호로 전환 시스템 도구를 제공하세요. 이 규칙에는 대상이 없습니다. 대화는 transfer-to-agent 결정으로 끝나고 시나리오가 발신자를 라우팅합니다. 전환 규칙은 API를 통해 구성합니다. 에이전트에 PATCH를 사용하여 도구를 추가하세요.

curl -X PATCH "https://api.elevenlabs.io/v1/convai/agents/agent_7101k5zvyjhmfg983brhmhkd98n6" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "conversation_config": {"agent": {"prompt": {"built_in_tools": {
      "end_call": {"type": "system", "name": "end_call", "description": "",
                   "params": {"system_tool_type": "end_call"}},
      "transfer_to_number": {
        "type": "system", "name": "transfer_to_number", "description": "",
        "params": {
          "system_tool_type": "transfer_to_number",
          "transfers": [],
          "transfer_rules": [{
            "condition": "the caller asks to speak with a human",
            "provider_configs": [
              {"type": "voximplant", "config": {"type": "voximplant_handoff"}}
            ]
          }]
        }
      }
    }}}}
  }'

end_call 등 이미 보유한 도구를 포함해 에이전트의 전체 built_in_tools 객체를 전송하세요. 에이전트가 다시 보내는 옵션은 고정 토큰 voximplant이므로 도구당 Voximplant 규칙 하나면 충분합니다. 다른 공급자에 대해 구성한 전화번호와 SIP URI는 Voximplant 통화에서 제공되지 않습니다.

전용 API 키 생성

에이전트와 동일한 워크스페이스에서 API 키를 생성하고 ElevenAgents 범위로 지정하세요. Voximplant에서만 연결을 허용하려면 키의 허용 IP 주소를 Voximplant 미디어 서버로 제한하세요. Voximplant 미디어 서버 목록은 https://api.voximplant.com/getMediaResources?with_mediaservers에서 확인할 수 있습니다.

WebSocket URL 확인

시나리오는 에이전트 ID가 포함된 URL에 연결합니다.

에이전트의 브랜치를 고정하려면 ?branch_id=<branch_id>를 추가하세요.

애플리케이션 생성

Voximplant 제어판에서 Applications를 열고 Create application을 클릭하세요. 예를 들어 elevenlabs-agent와 같은 이름을 지정하고 Create를 클릭하세요.

API 키를 시크릿으로 저장

애플리케이션에서 Secrets를 열고 Add secret을 클릭하세요. 이름을 ELEVENLABS_API_KEY로 지정하고, 에이전트 워크스페이스용으로 만든 API 키를 Value에 붙여 넣은 다음 Add secret을 클릭하세요. 시나리오는 VoxEngine.getSecretValue()로 이를 읽으므로 키가 시나리오 코드에 표시되지 않습니다.

시나리오 생성

Scenarios를 열고 Create scenario를 클릭한 다음 이름을 elevenlabs_agent로 지정하세요. 아래 코드를 붙여 넣고, ELEVENLABS_URL의 에이전트 ID를 바꾼 후 Save를 클릭하세요. 이 시나리오는 수신 전화를 받고 에이전트로 스트리밍하며, 대화가 끝나면 결정에 따라 동작합니다. 발신 통화의 경우 전화를 건 CallEvents.Connected 핸들러에서 WebSocket을 여세요.

const ELEVENLABS_URL =
  "wss://api.elevenlabs.io/v1/convai/conversation/voximplant/agent_7101k5zvyjhmfg983brhmhkd98n6";
VoxEngine.addEventListener(AppEvents.CallAlerting, ({ call }) => {
  call.answer();
  let decision = null;
  const ws = VoxEngine.createWebSocket(ELEVENLABS_URL, {
    headers: [
      {
        name: "Authorization",
        value: `Bearer ${VoxEngine.getSecretValue("ELEVENLABS_API_KEY")}`,
      },
    ],
  });
  ws.addEventListener(WebSocketEvents.OPEN, () => {
    call.sendMediaTo(ws, {
      encoding: WebSocketAudioEncoding.PCM16_8KHZ,
      customParameters: { customer_name: "Ana", task_id: "task-7" },
    });
    ws.sendMediaTo(call);
  });
  ws.addEventListener(WebSocketEvents.MESSAGE, ({ text }) => {
    const message = JSON.parse(text);
    if (message.customEvent === "elevenlabs-decision") {
      decision = message.payload;
      Logger.write(`ElevenLabs decision: ${JSON.stringify(decision)}`);
    }
  });
  ws.addEventListener(WebSocketEvents.CLOSE, (e) => {
    Logger.write(`ElevenLabs socket closed: code=${e.code} reason=${e.reason}`);
    if (decision?.action === "transfer-to-agent") {
      // Route the caller to a human here, for example with VoxEngine.callPSTN().
      call.say("Connecting you to an agent.", { language: VoiceList.Amazon.en_US_Joanna });
      call.addEventListener(CallEvents.PlaybackFinished, () => call.hangup());
      return;
    }
    call.hangup();
  });
  call.addEventListener(CallEvents.Disconnected, () => {
    ws.close();
    VoxEngine.terminate();
  });
});

통화를 시나리오로 라우팅

Routing을 열고 Create rule을 클릭한 다음 이름을 지정하고 elevenlabs_agent 시나리오를 할당하세요. 기본 패턴 .*는 애플리케이션으로 들어오는 모든 통화를 시나리오로 전송합니다. 애플리케이션에서 다른 통화도 처리하는 경우 특정 전화번호로 범위를 좁히세요. 전화번호를 라우팅하려면 Numbers에서 전화번호를 애플리케이션에 연결하세요.

테스트 통화하기

전화번호 없이도 브라우저에서 애플리케이션으로 전화를 걸 수 있습니다.

1. Users를 열고 Create user를 클릭한 다음 비밀번호가 있는 사용자를 생성하세요.

   

2. Routing에서 Test tools, Softphone 순으로 클릭하세요. 해당 사용자로 로그인하고 마이크 접근을 허용한 뒤, 아무 대상이나 입력하여 통화하세요. 에이전트가 첫 메시지로 응답합니다.

3. 통화가 끝나면 Call history를 여세요. 각 통화에는 통화 자체 옆에 WebSocket 레그가 표시됩니다. View log를 클릭하여 세션을 확인하세요.

   

   로그에는 ElevenLabs가 전송한 결정, WebSocket 종료, 그리고 시나리오가 이후 수행한 동작이 표시됩니다. 이 예에서 발신자는 상담원을 요청했으므로 에이전트가 제공한 사유와 함께 transfer-to-agent 결정이 내려집니다.