Open in
통화별 변수 및 컨텍스트
에이전트를 변경하지 않고 각 통화에 프롬프트용 명명된 변수 또는 자유 형식 브리프로 고유한 세부 정보를 제공합니다.
각 통화에는 통화별 입력 두 가지를 전달할 수 있습니다. 하나만 사용하거나 둘 다 함께 사용할 수 있습니다.
variables: 프롬프트의{{placeholders}}를 채우는 이름이 지정된 값입니다. 발신자 이름, 계정 번호 또는 예약 시간대처럼 프롬프트에서 이름으로 참조하는 필드에 사용합니다.context: 프롬프트 뒤에 추가되는 자유 형식 텍스트입니다. 이 통화의 작업 설명이나 이전에 수집한 메모처럼 템플릿에 맞지 않는 브리핑에 사용합니다.
아래에 설명된 모든 통화 시작 방법에서 저장된 에이전트 및 인라인 구성과 함께 모두 작동합니다. 어느 것도 저장된 에이전트, 버전 기록 또는 기타 설정을 변경하지 않습니다.
{
"agent_id": 12,
"variables": {"name": "Ada", "appointment_slot": "Tuesday at 10 AM"},
"context": "Ada rescheduled twice last month. She prefers mornings and asked us not to call her work number."
}변수
저장된 에이전트의 프롬프트에 자리표시자를 넣은 다음, 통화를 시작할 때 variables
객체를 제공합니다. ThunderPhone은 통화 구성을 음성 런타임으로 전송하기 전에 텍스트를 렌더링합니다.
값이 필요하지 않은 경우 variables를 생략하고 null을 전송하지 마세요(400으로 거부됨).
플레이스홀더 및 기본값
You are calling {{name|Friend}} about account {{account_id}}.
The available appointment is {{ appointment_slot }}.이름은 대소문자를 구분하며 [A-Za-z_][A-Za-z0-9_]*를 따릅니다. 이름 주변의 공백은
허용됩니다. | 뒤의 공백은 기본값의 일부이며 유지됩니다. {{name|Friend}}는 name이 없거나
null인 경우 Friend를 사용합니다. 빈 문자열은 명시적으로 제공된 값입니다. 기본값이 없는
누락된 값은 빈 문자열이 되며, 해당 이름은 unresolved_variables에 표시됩니다.
유효한 자리 표시자가 아닌 중괄호 두 개 사이의 텍스트는 제거됩니다. 제공된 각 값 안의 중괄호 두 개 텍스트도
독립적으로 제거됩니다. 값은 주변 프롬프트 텍스트나 다른 값을 제거할 수 없습니다. 짝이 맞지 않는
중괄호 두 개 구분자도 제거됩니다. 프롬프트의 JSON 예시에는 {{를 사용하면 안 됩니다.
값은 일반 텍스트이며 코드로 평가되거나 템플릿으로 재귀 확장되지 않습니다.
변수는 확인 프롬프트, 발신 음성사서함 메시지 및 전화 통화에 해당 필드가 전송되는 경우의
동의 안내 텍스트에도 사용할 수 있습니다. 에이전트에는 별도의 first_message 필드가 없습니다.
시작 지침은 프롬프트에 넣으세요. 기존 음성사서함 {agent_name} 및 {org_name}
자리 표시자는 계속 작동합니다.
값 및 제한
값은 문자열, 숫자, 불리언 또는 null일 수 있으며, 불리언은 true와
false로 렌더링됩니다. 줄바꿈(\n), 탭(\t), 캐리지 리턴(\r)을 제외한 유니코드 제어(Cc)
문자, 인도계 및 아랍 문자 언어에서 단어를 표기하는 폭 없는 비결합자와 결합자(U+200C, U+200D)를 제외한 형식(Cf)
문자, 그리고 서로게이트(Cs) 코드 포인트는 제거됩니다. \r\n은 \n으로 정규화됩니다. 각 값은
렌더링 시 2,000자로 제한됩니다. 제공된 문자열도 저장 전에 정리되고
잘립니다. 원본 객체는 UTF-8 JSON 32KB 이하여야 합니다. 더 큰 객체는 통화/세션 요청에서 400을 반환하며,
캠페인 가져오기는 잘못된 행을 개별적으로 보고합니다. 배열과 중첩 객체는 값으로
허용되지 않습니다. 일치하지 않는 메타데이터 키(예: 공백이 포함된 CSV 헤더)는 유지되고 에코되지만
플레이스홀더로 참조할 수 없습니다.
컨텍스트
context는 최대 20,000자의 문자열입니다. ThunderPhone은 프롬프트의 변수가 채워진 후
다음과 같은 구분 블록으로 프롬프트 뒤에 이를 추가합니다.
<your prompt, with its variables filled in>
Details for this call:
<call_context>
Ada rescheduled twice last month. She prefers mornings and asked us not to call her work number.
</call_context>에이전트는 지시와 함께 이를 읽으므로, 통화 전에 동료에게
브리핑하는 방식으로 작성합니다. 컨텍스트는 템플릿이 아닙니다.
내부의 {{name}}은 작성된 그대로 유지됩니다. 텍스트에 값이 필요하면 전송하기 전에
직접 값을 넣으십시오.
null, 빈 문자열 또는 공백만 있는 값은 컨텍스트가 없음을 의미합니다.- 문자열이 아니거나 20,000자를 초과하는 값은 통화 및 세션 요청에서
400과 함께 거부됩니다. 구성 webhook에서 전달된 경우에는 잘못된variables와 마찬가지로 교환이 실패합니다(아래 참조). - 앞뒤 공백은 제거되며, 변수 값과 동일한 제어 문자 및 형식 문자가 제거됩니다.
- 컨텍스트는 통화 프롬프트의 일부이므로 통화의 프롬프트 크기에 포함됩니다.
단계 에이전트에서는 컨텍스트가 각 단계의 지시가 아니라 통화에 포함된 모든 에이전트의 프롬프트 뒤에 추가됩니다.
값의 출처
아웃바운드 API
POST /v1/call에서 variables와 context를 전송합니다:
{
"from_number": "+15551234567",
"to_number": "+14155552671",
"agent_id": 12,
"variables": {
"name": "Ada",
"account_id": "A-17",
"appointment_slot": "Tuesday at 10 AM"
},
"context": "Ada asked to be called back about the late fee on her March invoice."
}둘 다 전화번호의 기본 발신 에이전트 또는 인라인 config.prompt와 함께 사용할 수 있습니다. 인라인 구성을 사용하는 경우 context는 구성 웹훅이 반환하는 동일한 필드인 config 내부에도 포함할 수 있습니다. 둘 다 전송하는 경우 텍스트가 동일해야 합니다. 서로 다른 변수 또는 서로 다른 컨텍스트에는 멱등성 키를 재사용할 수 없습니다.
캠페인 CSV
전화번호가 아닌 CSV 열은 이미 연락처 변수로 저장됩니다. 이제 각 발신에서 이러한 변수를 자동으로 사용합니다. 자리표시자에 맞게 name, account_id, appointment_slot과 같은 헤더를 사용합니다. 기존 이름 매핑은 이름 및 성 열을 name 변수로 결합할 수 있습니다. 캠페인 연락처에는 연락처별 컨텍스트가 없습니다.
동적 구성 웹훅
차단 구성 웹훅 경로에서 조직에 저장된 에이전트와 통화별 값을 반환합니다. Full duplex 에이전트의 경우 통화가 다른 지원 언어로 시작하더라도 에이전트의 음성이 유지됩니다. 언어별 음성 매핑과 기본 음성 전환은 해당 통화에 적용되지 않습니다.
{
"agent_id": 12,
"variables": {"name": "Ada", "account_id": "A-17"},
"context": "[REDACTED_LITERAL]"
}{
"agent_id": 12,
"variables": {"name": "Ada", "account_id": "A-17"},
"context": "Ada called yesterday about a leak in unit 4B; a plumber is booked for Friday."
}응답의 변수는 요청 수준 변수를 덮어쓰지만, 다른 요청 키는 유지됩니다. 응답 값이 null이면 자리 표시자의 기본값이 선택됩니다.
병합된 객체도 32 KB 이하여야 합니다. 저장된 에이전트 응답은
agent_id, variables, context, language 및 통화별
timezone만 허용합니다. 프롬프트 또는 기타 설정을
교체해야 하는 경우 인라인 구성을 반환합니다. 저장된 에이전트 웹훅
응답은 전화 및 위젯 통화 모두에서 에이전트에 배포된 A/B 분할을 사용하며,
변수는 변형 선택 후 렌더링됩니다. 응답이 Full duplex가 아닌
에이전트에 대해 language를 설정하면, 에이전트에 해당 언어의 음성이 설정되어 있는 경우 통화에서도 그 음성이 사용됩니다. prompt를 포함한 응답은 항상 인라인
구성을 사용합니다. 해당 응답의 모든 agent_id는 null 또는 정수가 아닌
메타데이터를 포함하여 무시됩니다. 인라인 프롬프트는 여전히 일반 검증을 통과해야 합니다.
인라인 웹훅 응답에도 variables와 context를 포함할 수 있습니다. context가
문자열이 아니거나 너무 길면 교환이 실패합니다. 전화 통화는
거부되고, 위젯 세션 요청은 400으로 실패합니다. 저장된 에이전트 웹훅
응답은 전화 및 위젯 통화 모두에서 에이전트에 배포된 A/B 분할을 사용하며,
변수는 변형 선택 후 렌더링됩니다. 인바운드 전화 통화에서는 할당된 인바운드
에이전트가 없는 번호를 사용하고 해당 전화번호 또는 조직 웹훅을 구성합니다. 위젯 키는
mode="webhook"를 사용합니다. 엔드포인트 시스템의 수신 알림은 차단 구성 응답을 제공하지 않습니다.
에이전트 통화 설정 웹훅
번호를 에이전트에 할당한 상태로 유지하고 통화별 값만 채우려면 에이전트에 통화 설정 웹훅을 추가합니다.
에이전트가 번호로 각 수신 전화를 받기 전에 웹훅은 통화와 에이전트의 ID, 이름, 버전을 받고, agent_id 없이도 위와 동일한 variables, context, language, 통화별 timezone을 포함해 응답합니다. 설정에서 기본값이 없는 플레이스홀더를 사용하는 에이전트는 전화에 응답하려면 이 웹훅이 필요합니다. 웹훅이 실패하면 통화가 시작되지 않습니다. {{name|there}}와 같이 기본값이 있는 플레이스홀더를 사용하면 웹훅 없이도 에이전트가 응답할 수 있습니다.
SIP 헤더
SIP를 통해 에이전트에 연결되는 통화(SIP 주소 또는 수동 SIP 연결의 번호)는 X-* 및 User-to-User 헤더에 컨텍스트를 포함할 수 있습니다. 각 헤더는 {{sip_x_amzn_connectcontactid}} 또는 {{sip_uui}}와 같은 sip_ 변수가 되며, 가장 낮은 우선순위를 가집니다. API 또는 웹훅에서 동일한 이름으로 제공된 값이 우선합니다. SIP 헤더로 통화 컨텍스트 전달을 참조하세요. 헤더 값은 발신자가 설정하므로 브라우저에서 제공되는 모든 값과 마찬가지로 신뢰할 수 없는 값으로 취급하세요.
위젯 세션 API
POST /v1/widget/session은 최상위 variables 및 language를 받습니다. 공개
키는 저장된 에이전트를 선택합니다. 웹훅 모드 키는 이러한 값을 구성
웹훅으로 전달하고 위에서 설명한 대로 응답을 병합합니다.
브라우저에서 제공된 위젯 variables는 클라이언트가 제어하며,
위에서 설명한 유효성 검사 및 문자열 정리 후 web.incoming에
그대로 전달되고 완료 웹훅 및 통화 기록에도 반영됩니다. 이를 신뢰할 수 있는
신원 또는 권한 부여 데이터로 취급하지 마세요.
위젯 자체의 브라우저 context 필드는 다릅니다. 이는 방문자가 있는
페이지의 텍스트를 전달하며, 에이전트는 이를 웹사이트 콘텐츠로 처리합니다(웹 위젯 임베드 참조).
위젯 통화의 통화별 컨텍스트는 위와 같이 웹훅 모드 키의 구성 웹훅에서 가져옵니다. 통화에
둘 다 있으면 통화별 컨텍스트가 먼저 오고 페이지 콘텐츠가 그 뒤에 옵니다.
실시간 세션 API
POST /v1/realtime/sessions는 agent_id 또는 인라인 config와 함께 최상위 수준의 variables, context, language를 허용합니다:
{
"agent_id": 12,
"variables": {"name": "Ada"},
"context": "Ada is calling from the front desk about a guest's lost key card."
}context는 최상위에만 둘 수 있습니다. 인라인 config에서는 이를
알 수 없는 필드로 거부합니다.
실시간 WebSocket
저장된 에이전트를 사용하는 경우, 저장된 에이전트의 배포된 프롬프트가 해당 에이전트의 프롬프트로 유지됩니다.
session.instructions는 통화의 컨텍스트가 되고, session.prompt.variables
(또는 session.config.variables)는 변수가 되며, session.language는
통화별 언어가 됩니다. 첫 번째 session.update에서 session.prompt.id로
에이전트를 선택합니다. 이 업데이트가 도착하면 세션이 시작됩니다:
{
"type": "session.update",
"session": {
"type": "realtime",
"prompt": {"id": "12", "variables": {"name": "Ada"}},
"instructions": "Ada asked for a callback about her delivery window."
}
}연결 URL의 ?agent_id=12는 소켓이 연결되는 즉시, 어떤 session.update보다 먼저
에이전트를 시작하므로 통화별 입력이 포함되지 않습니다. 첫 번째 session.update를 기다리고
해당 지침과 변수를 사용하려면 &wait_for_session_update=1을 추가합니다.
인라인 세션(저장된 에이전트 없음)에서는 이전과 마찬가지로 session.instructions 자체가 프롬프트입니다. 브라우저 테스트 통화와 시뮬레이션은 기본값과 누락된 자리 표시자를 확인합니다. 값으로 테스트하려면 에이전트에 통화 설정 샘플을 저장하고 테스트를 시작할 때 선택합니다. 그러면 통화 설정 웹훅이 해당 샘플로 응답한 것처럼 통화가 실행됩니다.
통화 후
GET /v1/calls, GET /v1/calls/{call_id}, telephony.complete, web.complete에는 최종 병합된 variables와 unresolved_variables가 포함됩니다. data.history를 포함하는 레거시 완료 페이로드에도 이 값이 포함됩니다.
{
"variables": {"name": "Ada", "account_id": "A-17"},
"unresolved_variables": ["appointment_slot"]
}통화의 prompt_snapshot(GET /v1/calls/{call_id})은 변수가 채워지고 컨텍스트 블록이 추가된 에이전트의 프롬프트를 보여줍니다.
완료된 통화를 원본 레코드에 다시 연결하려면 CRM 또는 작업 식별자를 변수 객체에 저장합니다. 변수와 컨텍스트는 통화 레코드와 함께 유지됩니다. 통화 기록과 웹훅에 보관해도 되는 정보만 전송합니다.
검증 세트, 리플레이 실행, 조사에서 통화를 리플레이하면 테스트 중인 프롬프트와 함께 해당 통화의 변수 및 컨텍스트를 사용합니다. 따라서 리플레이는 해당 통화의 에이전트가 어떤 정보를 전달받았을지를 테스트합니다.
기존 프롬프트 호환성
렌더링은 기존 저장된 에이전트 및 A/B 변형 프롬프트, 인라인
아웃바운드 및 실시간 구성, 그리고 구성 웹훅에서 반환되는 프롬프트에도 적용됩니다. variables가 제공되지 않은 경우에도 알 수 없는 {{name}} 자리 표시자는 빈 텍스트가 됩니다. ThunderPhone이 목록화할 수 없는 외부 제공 인라인/웹훅 프롬프트를 포함하여, 출시 전에 기존 프롬프트를 확인합니다.
브라우저 테스트 통화와 시뮬레이션에도 동일한 기본값/빈 값 동작이 적용됩니다.
단, 저장된 통화 설정 샘플을 선택한 경우는 예외입니다.