통화 대기열

개요

에이전트 또는 워크스페이스가 동시성 한도에 도달하면 일반적으로 새 통화는 즉시 거절됩니다. 통화 대기열을 활성화하면 에이전트의 수용량이 가득 찬 동안 도착한 발신자는 대기 오디오를 들으며 회선에서 대기하고, 자리가 나는 즉시 도착한 순서대로 자동 연결됩니다.

통화 대기열은 에이전트별로 구성하며, 새 에이전트에서는 기본적으로 활성화되어 있습니다.

통화 대기열 작동 방식

1. 용량 확인: 통화가 도착하면 ElevenAgents는 에이전트와 워크스페이스에 사용 가능한 동시성 슬롯이 있는지 확인합니다. 있으면 통화가 즉시 연결됩니다.
2. 대기열 등록: 사용 가능한 슬롯이 없으면 발신자는 에이전트의 대기열에서 대기하며 대기 오디오를 듣습니다. 발신자가 대기하는 동안에는 대화가 시작되지 않으며 요금도 청구되지 않습니다.
3. 연결 허용: 슬롯이 생기는 즉시 대기열 맨 앞의 발신자가 연결되고, 평소처럼 대화가 시작됩니다.
4. 시간 초과: 최대 대기열 대기 시간 내에 슬롯이 생기지 않으면 통화가 종료됩니다. 전화 통화는 일반적으로 끊깁니다. WebSocket 클라이언트는 상태가 timed_out인 queue_status 이벤트를 받은 후 코드 4300으로 연결이 종료됩니다.

특정 에이전트의 발신자는 도착 순서대로 엄격하게 연결됩니다. 여러 에이전트가 워크스페이스의 동시성 풀을 공유하는 경우에는 일반적으로 더 오래 대기한 발신자가 먼저 연결됩니다.

발신자가 듣는 내용

• Twilio 및 SIP 트렁크 번호의 전화 발신자는 통화 중 대기 오디오를 듣습니다.
• 위젯 및 브라우저 SDK 사용자는 브라우저에서 대기 오디오를 듣습니다. 위젯(버전 0.17.0 이상)은 대기열에 있는 동안 대기 메시지를 표시하고 텍스트 입력을 비활성화합니다.
• 직접 WebSocket API 클라이언트는 일반 audio 이벤트로 대기 오디오를 받고, 자체 UI에서 대기 상태를 구현할 수 있도록 queue_status 이벤트도 받습니다. 대기열 이벤트 처리를 참조하세요.

요금 및 대화 시간

대기열에서 보낸 시간은 요금이 청구되지 않으며, 에이전트의 최대 대화 시간에 포함되지 않고, 대화에 보고되는 시간에도 포함되지 않습니다. 대시보드의 대화 세부 정보에서는 발신자가 연결되기 전까지 대기한 시간을 확인할 수 있습니다.

지원 채널

구성

통화 대기열은 에이전트의 보안 탭에 있는 한도 섹션에서 에이전트별로 구성합니다.

새 에이전트는 queueing_config.enabled가 true로 설정된 상태로 생성됩니다. 통화 대기열을 끈 상태로 에이전트를 만들려면 생성 요청에서 queueing_config.enabled를 false로 설정하세요.

API를 통한 대기 오디오 관리

에이전트의 사용자 지정 대기 오디오를 설정하려면 MP3 또는 WAV 파일을 업로드하세요. 새 파일을 업로드하면 이전 파일이 교체됩니다. API는 audio/mpeg 및 audio/wav 콘텐츠 유형을 지원하므로, 예시에서는 유형을 명시적으로 설정합니다.

from dotenv import load_dotenv
from elevenlabs import ElevenLabs
import os
load_dotenv()
elevenlabs = ElevenLabs(
api_key=os.getenv("ELEVENLABS_API_KEY"),
)
elevenlabs.conversational_ai.agents.hold_audio.create(
agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
hold_audio_file=("hold-music.mp3", open("hold-music.mp3", "rb"), "audio/mpeg"),
)

사용자 지정 클립을 제거하면 기본 대기음으로 돌아갑니다:

elevenlabs.conversational_ai.agents.hold_audio.delete(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
)

현재 클립은 에이전트에서 platform_settings.queueing_config.hold_audio로 읽기 전용 반환됩니다. 에이전트 생성 또는 업데이트 요청에서 hold_audio를 전송해도 적용되지 않습니다.

사용자 지정 WebSocket 클라이언트에서 대기열 이벤트 처리

WebSocket API를 통해 연결된 클라이언트는 대기열에 있는 동안 queue_status 이벤트를 받습니다:

{
  "type": "queue_status",
  "queue_status_event": {
    "status": "waiting"
  }
}

• waiting은 conversation_initiation_metadata 직후, 대기 오디오가 시작되기 전에 한 번 전송됩니다.
• admitted는 발신자가 연결될 때 전송됩니다. 이후 대화는 평소처럼 진행됩니다.
• timed_out은 대기 시간이 최대 대기열 대기 시간을 초과하면 전송됩니다. 그러면 서버가 코드 4300으로 연결을 종료합니다.

즉시 연결되는 통화는 queue_status 이벤트를 받지 않습니다. 이 이벤트는 항상 대기열의 발신자에게 전송되며 에이전트의 client_events에서 활성화할 필요가 없습니다.

대기 오디오는 에이전트의 클라이언트 이벤트에 audio가 포함된 경우, 약 1초 단위의 일반 audio 이벤트로 전송됩니다. 대기 오디오를 에이전트 발화로 처리하지 말고 queue_status를 사용해 대기 상태를 표시하세요.

FAQ