번호로 전환

정의된 조건에 따라 통화를 외부 전화번호 또는 SIP URI로 전환합니다.

개요

transfer_to_number 시스템 도구를 사용하면 특정 조건이 충족될 때 ElevenLabs 에이전트가 진행 중인 통화를 지정된 전화번호 또는 SIP URI로 전환할 수 있습니다. 이를 통해 에이전트는 복잡한 문제, 특정 요청 또는 상담원 개입이 필요한 상황을 실제 상담원에게 전달할 수 있습니다.

이 기능은 Twilio 및 SIP 트렁크 번호를 통한 전환을 지원합니다. 트리거되면 에이전트는 사용자가 대기하는 동안 안내 메시지를 제공하고, 통화를 받는 상담원에게 상황을 요약한 별도의 메시지를 전달할 수 있습니다.

transfer_to_number 시스템 도구는 전화 통화에서만 사용할 수 있으며 채팅 위젯에서는 사용할 수 없습니다.

전환 유형

시스템은 세 가지 전환 유형을 지원합니다.

  • 컨퍼런스 전환: 기본 동작으로, 대상에 전화를 걸어 참가자를 컨퍼런스 룸에 추가한 다음 AI 에이전트를 제거합니다. 이후 발신자와 전환된 참가자만 남습니다. 네이티브 Twilio 통합을 사용하는 경우, 상담원에게 읽어 주는 웜 전환 메시지(agent_message)를 지원합니다.
  • 블라인드 전환: 상담원에게 웜 전환 메시지를 전달하지 않고 통화를 대상에게 직접 전환합니다. 원래 발신자 ID가 유지됩니다. 에이전트의 전화번호를 네이티브 Twilio 통합을 통해 가져온 경우에만 사용할 수 있습니다.
  • SIP REFER 전환: SIP REFER 프로토콜을 사용하여 통화를 대상에게 직접 전환합니다. 전화번호와 SIP URI 모두에서 작동하지만, 대화 중 SIP 프로토콜을 사용해야 하며 SIP 트렁크에서 SIP REFER를 통한 전환을 허용해야 합니다. 웜 전환 메시지는 지원하지 않습니다.

웜 전환 메시지(agent_message)는 에이전트의 전화번호를 네이티브 Twilio 통합을 통해 가져온 경우에만 사용할 수 있습니다. SIP 기반 전환은 웜 전환 메시지를 지원하지 않습니다.

블라인드 전환은 에이전트의 전화번호를 네이티브 Twilio 통합을 통해 가져온 경우에만 사용할 수 있으며, 현재 UI의 JSON 편집기에서 구성해야 합니다. 전환 도구 구성에서 “Edit as JSON”을 선택한 후 원하는 전환 규칙에 "transfer_type": "blind"를 설정하세요.

목적: AI 지원만으로 부족할 때 대화를 상담원에게 원활하게 연결합니다.

실행 조건: 다음 경우 LLM이 이 도구를 호출해야 합니다.

  • 사람의 판단이 필요한 복잡한 문제인 경우
  • 사용자가 상담원 지원을 명시적으로 요청한 경우
  • 특정 요청에 대해 AI의 역량 한계에 도달한 경우
  • 에스컬레이션 프로토콜이 실행된 경우

매개변수:

  • reason (문자열, 선택): 연결을 전환하는 이유
  • transfer_number (문자열, 필수): 연결을 전환할 전화번호(구성된 번호와 일치해야 함)
  • client_message (문자열, 필수): 연결을 기다리는 동안 고객에게 읽어줄 메시지
  • agent_message (문자열, 필수): 통화를 받는 상담원에게 전달할 메시지

함수 호출 형식:

{
"type": "function",
"function": {
"name": "transfer_to_number",
"arguments": "{\"reason\": \"Complex billing issue\", \"transfer_number\": \"+15551234567\", \"client_message\": \"I'm transferring you to a billing specialist who can help with your account.\", \"agent_message\": \"Customer has a complex billing dispute about order #12345 from last month.\"}"
}
}

구현: 연결 전환 전화번호와 조건을 구성하세요. 고객과 통화를 받는 상담원 모두에게 전달할 메시지를 정의하세요. Twilio와 SIP 트렁킹을 모두 지원합니다.

전환 가능한 번호

상담원 전환은 SIP 트렁킹과 Twilio 전화번호를 모두 사용하여 외부 전화번호로 전환할 수 있습니다.

상담원 전환 활성화

상담원 전환은 transfer_to_number 시스템 도구를 사용하여 구성합니다.

1

전환 도구 추가

Agent 탭의 에이전트 구성에서 transfer_to_number 시스템 도구를 선택하여 상담원 전환을 활성화합니다. 도구를 추가할 때 “Transfer to Human”을 선택하세요.

상담원 전환 도구 추가
'Transfer to Human' 도구 선택
2

도구 설명 구성(선택 사항)

LLM에 전환을 트리거할 시점을 안내하는 맞춤 설명을 제공할 수 있습니다. 비워 두면 정의된 전환 규칙을 포함하는 기본 설명이 사용됩니다.

상담원 전환 도구 설명
전환 도구 설명 구성
3

전환 규칙 정의

전화번호 또는 SIP URI로 전환하기 위한 구체적인 규칙을 구성합니다. 각 규칙에서 다음을 지정하세요.

  • 전환 유형: 컨퍼런스(기본값), 블라인드 또는 SIP REFER 전환 방식 중에서 선택
  • 번호 유형: 일반 전화번호는 Phone, SIP 주소는 SIP URI 선택
  • 전화번호/SIP URI: 적절한 형식의 대상 주소:
  • 조건: 전환이 발생해야 하는 상황에 대한 자연어 설명(예: “사용자가 명시적으로 상담원과의 대화를 요청함”, “사용자가 민감한 계정 정보를 업데이트해야 함”)

LLM은 도구 설명과 함께 이러한 조건을 사용하여 전환 시점과 대상을 결정합니다.

SIP REFER 전환은 대화 중 SIP 프로토콜이 필요하며 SIP 트렁크에서 SIP REFER를 통한 전환을 허용해야 합니다. SIP URI로 전환을 지원하는 방식은 SIP REFER뿐입니다.

블라인드 전환은 에이전트의 전화번호를 네이티브 Twilio 통합을 통해 가져온 경우에만 사용할 수 있으며 JSON 편집기에서 구성해야 합니다. 원래 발신자 ID는 유지되지만 상담원에게 웜 전환 메시지는 전송되지 않습니다.

상담원 전환 규칙 구성
전화번호와 조건으로 전환 규칙 정의

대상 주소 형식이 올바른지 확인하세요.

  • 전화번호: E.164 형식이며 올바르게 구성된 계정과 연결되어야 함
  • SIP URI: 유효한 SIP 형식(sip:user@domain 또는 sips:user@domain)
4

맞춤 SIP REFER 헤더 구성(선택 사항)

SIP REFER 전환을 사용할 때 맞춤 SIP 헤더를 포함하여 수신 시스템에 추가 정보를 전달할 수 있습니다.

각 맞춤 헤더에서 다음을 지정하세요.

  • 헤더 이름: SIP 헤더 이름(예: X-Customer-ID, X-Priority)
  • 헤더 값: 정적 텍스트이거나 동적 변수를 포함할 수 있는 헤더 값

맞춤 SIP REFER 헤더는 SIP REFER 전환에만 포함됩니다. 컨퍼런스 전환은 맞춤 헤더를 지원하지 않습니다.

시스템 헤더 X-Conversation-ID 및 X-Caller-ID는 ElevenLabs에서 자동으로 포함하며, 이름이 동일한 맞춤 헤더는 대소문자를 구분하지 않고 덮어씁니다.

5

User-to-User Information(UUI) 구성(선택 사항)

SIP REFER 전환은 Refer-To 헤더의 User-to-User 매개변수에서 수신 플랫폼(예: Talkdesk 또는 Genesys Cloud)에 전달되는 작은 페이로드인 User-to-User Information(UUI)를 전달할 수 있습니다. UUI는 SIP URI로의 SIP REFER 전환에서만 전송되며, 전화번호(tel:) 대상에는 전달되지 않습니다.

uui 객체를 사용하여 전환 규칙별로 UUI를 구성합니다.

  • data: 일반 텍스트로 전송할 페이로드입니다. ElevenLabs가 이를 16진수로 인코딩하고 ;encoding=hex를 추가합니다. 정적 텍스트이거나 동적 변수를 포함할 수 있습니다. 최대 256바이트(UTF-8)이며, 동적 변수 치환 후 적용됩니다. 일반 ASCII의 경우 256자이지만 멀티바이트 문자는 더 적습니다.
  • protocol_discriminator: 예를 들어 04와 같은 단일 16진수 옥텟입니다. 플랫폼이 페이로드의 첫 번째 옥텟을 제거하는 경우 포함하고, 페이로드를 그대로 전달하는 플랫폼에서는 생략하세요.
  • protocol_discriminator_mode: prefix(기본값)는 옥텟을 앞에 추가하여 04<hex>;encoding=hex를 생성합니다. pd_parameter는 별도 매개변수로 추가하여 <hex>;pd=04;encoding=hex를 생성합니다.

Talkdesk는 값을 변경 없이 전달하므로 프로토콜 식별자를 생략하세요. Genesys Cloud는 식별자가 없으면 페이로드의 첫 번째 옥텟을 제거하므로 protocol_discriminator를 포함하세요. Genesys UUI 데이터 형식을 참조하세요.

256바이트 제한은 동적 변수를 치환한 후 적용됩니다. 전체 통화 요약처럼 제한을 초과하여 전환에서 제거되는 자유 형식 텍스트 대신 계정 ID와 같은 식별자나 짧은 코드를 전달하세요.

수신 SIP 통화에서 UUI를 받기 위해 별도 구성은 필요하지 않습니다. 수신 INVITE에 User-to-User 헤더가 포함된 경우, 그 값은 에이전트에서 {{sip_uui_raw}} 및 {{sip_uui_data}} 동적 변수로 노출됩니다. SIP 레퍼런스를 참조하세요.

6

통화 후 다이얼 숫자 구성(선택 사항)

통화 후 다이얼 숫자는 전화가 전환 대상에 연결된 후 전달되는 DTMF 톤입니다. 내선 번호를 입력하거나 IVR(Interactive Voice Response) 메뉴를 자동으로 탐색하는 데 유용합니다.

각 전환 규칙에서 다음을 포함하는 post_dial_digits 문자열을 지정할 수 있습니다.

  • 숫자(0-9): 표준 DTMF 톤
  • w: 0.5초 지연
  • W: 1초 지연
  • * 및 #: 특수 DTMF 톤

예를 들어 ww1234는 통화가 연결된 후 1초 동안 대기한 다음 내선 1234를 누릅니다.

통화 후 다이얼 숫자는 에이전트의 전화번호(전환을 시작하는 번호)를 네이티브 Twilio 통합을 통해 가져온 경우에만 사용할 수 있습니다. 대상 번호는 어떤 전화번호든 가능합니다.

통화 후 다이얼 숫자는 컨퍼런스 및 블라인드 전환 유형에서만 지원됩니다. SIP REFER 전환은 통화 후 다이얼 숫자를 지원하지 않습니다.

API 구현

API를 통해 에이전트를 생성하거나 업데이트할 때 transfer_to_number 시스템 도구를 구성할 수 있습니다(에이전트 생성, 에이전트 업데이트). 이 도구를 사용하면 클라이언트(전환되는 사용자)와 에이전트(통화를 받는 상담원) 모두에게 전달할 메시지를 지정할 수 있습니다.

from elevenlabs import AgentConfig, ConversationalConfig, ElevenLabs
elevenlabs = ElevenLabs(api_key="YOUR_API_KEY")
# Define transfer rules
transfer_rules = [
{
"transfer_destination": {"type": "phone", "phone_number": "+15551234567"},
"condition": "When the user asks for billing support.",
"transfer_type": "conference",
# Wait 1s, then dial extension 1234 (native Twilio only)
"post_dial_digits": {"type": "static", "value": "ww1234"},
},
{
"transfer_destination": {"type": "phone", "phone_number": "+15559876543"},
"condition": "When the user asks to speak to a human.",
# Native Twilio integration only, preserves caller ID, no warm transfer message
"transfer_type": "blind",
},
{
"transfer_destination": {"type": "sip_uri", "sip_uri": "sip:support@example.com"},
"condition": "When the user requests to file a formal complaint.",
"transfer_type": "sip_refer",
"custom_sip_headers": [
{"type": "static", "key": "X-Department", "value": "complaints"},
{"type": "static", "key": "X-Priority", "value": "high"},
# Use "dynamic" to read the value from a dynamic variable
{"type": "dynamic", "key": "X-Customer-ID", "value": "{{customer_id}}"},
],
"uui": {
"data": "account_id={{customer_id}}",
"protocol_discriminator": "04", # Genesys Cloud; omit for Talkdesk
"protocol_discriminator_mode": "prefix", # or "pd_parameter"
},
},
]
response = elevenlabs.conversational_ai.agents.create(
conversation_config=ConversationalConfig(
agent=AgentConfig(
first_message="Hi, how can I help you today?",
prompt={
"prompt": "You are a helpful assistant.",
"built_in_tools": {
"transfer_to_number": {
"type": "system",
"name": "transfer_to_number",
# Optional custom description
"description": "Transfer the user to a human operator based on their request.",
"params": {
"system_tool_type": "transfer_to_number",
"transfers": transfer_rules,
},
}
},
},
),
),
)
# Note: When the LLM decides to call this tool, it needs to provide:
# - transfer_number: The phone number to transfer to (must match one defined in rules).
# - client_message: Message read to the user during transfer.
# - agent_message: Message read to the human operator receiving the call (native Twilio integration only, not used for blind transfers or SIP).