탐색으로 건너뛰기

개인화

동적 변수와 오버라이드를 사용해 에이전트의 동작을 개인화하는 방법을 알아보세요.

개요

개인화를 사용하면 각 사용자에 맞게 에이전트의 동작을 조정하여 더 자연스럽고 상황에 맞는 대화를 제공할 수 있습니다. ElevenLabs는 여러 개인화 방식을 제공합니다.

  1. 동적 변수 - 프롬프트와 메시지에 런타임 값을 삽입
  2. 오버라이드 - 시스템 프롬프트 또는 메시지를 완전히 교체
  3. 대화 시작 웹훅 - 대화가 시작될 때 서버에서 해당 데이터 가져오기

개인화 방법

대화 시작 클라이언트 데이터 구조

conversation_initiation_client_data 객체는 대화를 시작할 때 사용자 지정할 수 있는 항목을 정의합니다. 클라이언트에서 직접 전송할 수 있습니다. 대화 시작 웹훅도 동일한 객체를 반환합니다.

{
"type": "conversation_initiation_client_data",
"conversation_config_override": {
"agent": {
"prompt": {
"prompt": "overriding system prompt",
"llm": "gpt-5.6-luna"
},
"first_message": "overriding first message",
"language": "en"
},
"tts": {
"voice_id": "voice-id-here"
},
"conversation": {
"text_only": false
},
"asr": {
"keywords": ["Acme Corp", "Contoso"]
}
},
"custom_llm_extra_body": {
"temperature": 0.7,
"max_tokens": 100
},
"dynamic_variables": {
"string_var": "text value",
"number_var": 1.2,
"integer_var": 123,
"boolean_var": true
},
"user_id": "your_custom_user_id",
"branch_id": "agtbrch_xxxx",
"environment": "production",
"starting_workflow_node_id": "node_xxxx",
"procedure_ids": ["agtprc_xxxx", "agtprc_yyyy"],
"start_procedure_ids": ["agtprc_xxxx"]
}

모든 필드는 선택 사항입니다.

필드설명
conversation_config_override대화별 오버라이드입니다. 각 필드를 오버라이드하려면 에이전트의 Security 탭에서 해당 오버라이드를 활성화해야 합니다.
custom_llm_extra_body커스텀 LLM 요청에 병합되는 추가 JSON입니다. Custom LLM extra body 오버라이드가 필요합니다.
dynamic_variables에이전트의 동적 변수 값입니다.
user_id여러 대화에서 사용자를 식별하는 데 사용하는 최종 사용자 ID입니다.
source_info대화를 시작한 클라이언트와 해당 버전입니다. 소스 정보를 참조하세요.
branch_id실행할 에이전트 브랜치입니다. 기본값은 에이전트의 기본 브랜치입니다.
environment환경 변수를 확인하는 데 사용되는 환경입니다. 기본값은 production입니다.
starting_workflow_node_id시작 노드 대신 이 노드에서 workflow를 시작합니다. Workflow start node 오버라이드가 필요합니다. 지원되지 않는 노드 유형은 대화 시작에 실패합니다. workflow에 없는 ID는 무시되며, 대화는 시작 노드에서 시작됩니다.
procedure_ids대화를 이 절차로 제한합니다. 빈 배열은 에이전트의 모든 절차를 비활성화합니다. 대화가 시작되는 에이전트에만 적용됩니다. Procedures 오버라이드가 필요합니다.
start_procedure_ids대화와 함께 시작되는 자유 형식 절차이며, 최대 5개까지 가능합니다. Procedures 오버라이드가 필요합니다.

시스템 동적 변수(system__ 접두사가 있는 변수)는 클라이언트 시작 페이로드에서 전송하거나 오버라이드할 수 없습니다. dynamic_variables 필드를 통해 설정할 수 있는 것은 사용자 지정 동적 변수뿐입니다.

소스 정보

source_info는 어떤 클라이언트가 대화를 시작했는지 기록합니다. 소스는 대화에 저장되며, 대화 목록 엔드포인트에서 이를 기준으로 필터링할 수 있습니다.

{
"source_info": {
"source": "js_sdk",
"version": "1.2.3"
}
}
필드설명
source클라이언트 유형입니다. API 레퍼런스의 ConversationInitiationSource 값이어야 합니다. 다른 값은 검증에 실패합니다.
version최대 50자의 클라이언트 버전입니다.

ElevenLabs SDK와 위젯은 js_sdk, react_sdk, react_native_sdk, python_sdk, swift_sdk, android_sdk, flutter_sdk, widget 소스를 자동으로 보고합니다. 커스텀 클라이언트는 source_info를 생략할 수 있습니다. 자체 메타데이터 용도로 사용하지 말고 dynamic_variables를 사용하세요.

ElevenAgents는 전화, 메시징, 통합, 템플릿 미리보기 및 하위 에이전트 실행에 대해 자체적으로 소스를 설정합니다. 예를 들어 twilio, sip_trunk, whatsapp, zendesk_integration, template_preview, subagent_tool이 있습니다. 대화 시작 웹훅 응답은 이를 변경하지 않습니다.

대화 시작 웹훅

수신 전화 및 메시징의 경우, ElevenAgents는 클라이언트 대신 서버에서 이 시작 데이터를 가져올 수 있습니다. 웹훅이 활성화되면 ElevenAgents는 POST 요청을 보내고 반환한 JSON을 적용합니다.

Agents 설정에서 웹훅 URL과 헤더 시크릿을 구성하세요. 에이전트의 Security 탭에서 Fetch initiation client data from a webhook 및 응답에 포함될 수 있는 오버라이드 필드를 활성화하세요.

시작 클라이언트 데이터가 아직 없는 경우, 웹훅은 Twilio 음성, Exotel, SIP 트렁크, WhatsApp 또는 Twilio SMS의 새 수신 대화에 대해 실행됩니다. 또한 Amazon Connect 세션에서도 실행되며, 이 경우 응답은 Amazon Connect가 제공하는 연락처 컨텍스트와 병합됩니다.

발신 Twilio 음성, Exotel, SIP 및 WhatsApp 통화는 발신 요청에 conversation_initiation_client_data가 포함되지 않은 경우에만 이를 트리거합니다. 발신 WhatsApp 메시지는 절대 트리거하지 않으므로, 대신 발신 요청에 동적 변수를 전달하세요.

위젯 또는 SDK 대화, 기타 메시징 통합, 재개된 WhatsApp 및 SMS 스레드에서는 실행되지 않습니다.

에이전트 설정 페이지에서 시작한 미리보기 대화는 대화 시작 웹훅을 트리거하지 않습니다. 미리보기에서 테스트하는 동안에는 에이전트 편집기의 Dynamic Variables 플레이스홀더를 사용하세요. 이 플레이스홀더는 프로덕션 수신 대화에서는 사용되지 않습니다.

ElevenAgents는 요청 본문으로 발신자 컨텍스트를 전송합니다.

{
"caller_id": "+15551234567",
"called_number": "+15557654321",
"agent_id": "agent_7101k5zvyjhmfg983brhmhkd98n6",
"call_sid": "CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"conversation_id": "conv_8901k5zvyjhmfg983brhmhkd98n6"
}

caller_id와 called_number는 Twilio, Exotel, SIP 및 SMS에서 전화번호입니다. 수신 WhatsApp에서는 WhatsApp 사용자 ID와 WhatsApp 전화번호 ID입니다. 발신 통화에서 caller_id는 내 번호이고 called_number는 전화를 거는 상대방입니다. call_sid는 전화 통화에서는 제공업체 통화 SID이며, WhatsApp, SMS 및 Amazon Connect에서는 빈 문자열입니다. SIP 통화에는 call_id와 sip_headers가 추가로 포함될 수 있습니다. Amazon Connect 세션에는 연락처 ID로 설정된 call_id가 포함됩니다.

응답은 위의 conversation_initiation_client_data 형식을 사용해야 합니다. 에이전트가 정의한 모든 사용자 지정 동적 변수를 포함하세요. 오버라이드는 선택 사항이며 Security에서 활성화해야 합니다. HTTP 응답 본문은 256KB 이하(262,144바이트)여야 합니다.

실패하거나 시간이 초과된 웹훅은 대화 시작을 방해할 수 있습니다. Twilio 설정은 Twilio 개인화를 참조하세요. 이 웹훅은 통화 후 웹훅과 별개입니다.

적절한 방식 선택하기

방식적합한 용도구현
동적 변수
  • 템플릿 콘텐츠에 사용자별 데이터 삽입 - 개인화된 세부 정보와 함께 일관된 에이전트 동작 유지 - 도구 매개변수 개인화
{{ variable_name }}으로 변수를 정의하고 런타임에 값을 전달
오버라이드
  • 사용자별로 에이전트 동작을 완전히 변경 - 언어 또는 음성 전환 - 레거시 애플리케이션(동적 변수로 마이그레이션 고려)

보안 설정에서 특정 오버라이드 권한을 활성화하고 완전한 대체 콘텐츠를 전달

대화 시작 웹훅
  • 서버에서 수신 Twilio, SIP, WhatsApp 또는 SMS 대화 개인화 - 대화가 시작되기 전 발신자 컨텍스트 조회

Security 설정에서 웹훅을 활성화하고 conversation_initiation_client_data를 반환

자세히 알아보기