Developer cookbook

통화별 변수

배포된 프롬프트, 도구 또는 설정을 변경하지 않고 통화마다 저장된 에이전트를 개인화합니다.

저장된 에이전트의 프롬프트에 자리 표시자를 넣은 다음, 통화를 시작할 때 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) 문자, 모든 형식(Cf) 문자 및 서로게이트(Cs) 코드 포인트는 제거되며, \r\n은 \n으로 정규화됩니다. 각 값은 렌더링 시 2,000자로 제한됩니다. 제공된 문자열도 저장 전에 정리되고 잘립니다. 원본 객체는 UTF-8 JSON 기준 32KB 이하여야 합니다. 더 큰 객체는 통화/세션 요청에서 400을 받으며, 캠페인 가져오기는 잘못된 행을 개별적으로 보고합니다. 배열과 중첩 객체는 값으로 허용되지 않습니다. 일치하지 않는 메타데이터 키(예: 공백이 포함된 CSV 헤더)는 유지되고 반환되지만 자리 표시자로 참조할 수 없습니다.

값의 출처#

아웃바운드 API#

POST /v1/call에서 agent_id와 함께 variables를 전송합니다.

{
  "from_number": "+15551234567",
  "to_number": "+14155550199",
  "agent_id": 12,
  "variables": {
    "name": "Ada",
    "account_id": "A-17",
    "appointment_slot": "Tuesday at 10 AM"
  }
}

전화번호의 기본 아웃바운드 에이전트 또는 인라인 config.prompt와 함께 사용할 수도 있습니다. 서로 다른 변수를 사용하여 멱등성 키를 재사용할 수 없습니다.

캠페인 CSV#

전화번호가 아닌 CSV 열은 이미 연락처 변수로 저장됩니다. 이제 각 발신은 이를 자동으로 사용합니다. 플레이스홀더와 일치하도록 name, account_id, appointment_slot 등의 헤더를 사용합니다. 기존 이름 매핑은 이름 및 성 열을 name 변수로 결합할 수 있습니다.

동적 구성 웹훅#

블로킹 구성 웹훅 경로에서 조직에 저장된 에이전트와 통화별 값을 반환합니다.

{"agent_id": 12, "variables": {"name": "Ada", "account_id": "A-17"}}

응답의 키는 요청 수준 변수를 덮어쓰며, 다른 요청 키는 유지됩니다. 응답 값이 null이면 플레이스홀더의 기본값이 선택됩니다. 병합된 객체도 32 KB 이하여야 합니다. 저장된 에이전트 응답은 agent_id와 variables만 허용합니다. 프롬프트나 설정을 교체해야 하는 경우 인라인 구성을 반환합니다. prompt를 포함한 응답은 항상 인라인 구성을 사용합니다. 해당 응답의 모든 agent_id는 null 또는 정수가 아닌 메타데이터를 포함하여 무시됩니다. 인라인 프롬프트는 여전히 일반 검증을 통과해야 합니다. 인라인 웹훅 응답에도 variables를 포함할 수 있습니다. 저장된 에이전트 웹훅 응답은 전화 및 위젯 호출 모두에서 에이전트에 배포된 A/B 분할을 사용하며, 변수는 변형 선택 후 렌더링됩니다. 인바운드 전화 통화에서는 할당된 인바운드 에이전트가 없는 번호를 사용하고 해당 전화번호 또는 조직 웹훅을 구성합니다. 위젯 키는 mode="webhook"를 사용합니다. 엔드포인트 시스템 수신 알림은 블로킹 구성 응답을 제공하지 않습니다.

위젯 및 Realtime 세션 API#

POST /v1/widget/session은 최상위 variables 객체를 허용합니다. 게시 가능 키가 저장된 에이전트를 선택합니다. 웹훅 모드 키는 이러한 값을 구성 웹훅으로 전달하고 위에서 설명한 대로 응답을 병합합니다. 브라우저에서 제공하는 위젯/Realtime variables는 클라이언트가 제어하며, 위에서 설명한 검증 및 문자열 정리 후 web.incoming에 있는 그대로 전달되고 완료 웹훅 및 통화 기록에 그대로 포함됩니다. 이를 신뢰할 수 있는 신원 또는 권한 부여 데이터로 취급하지 마십시오.

POST /v1/realtime/sessions는 agent_id(또는 인라인 config)와 함께 variables를 허용합니다. 이는 세션 생성 API 필드입니다. Realtime WebSocket 브리지는 variables 옵션을 전달하지 않으므로 세션 생성 API에 직접 제공합니다. 위젯 클라이언트는 게시된 세션 페이로드에 variables를 포함해야 하며, SDK 전달은 이 API 변경 사항에 포함되지 않습니다. 빌더 마이크 및 시뮬레이션 테스트 통화는 기본값과 누락된 플레이스홀더를 확인하지만 통화별 변수 입력은 없습니다.

통화 후 반환되는 값#

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"]
}

완료된 통화를 원본 레코드와 연결하려면 CRM 또는 작업 식별자를 variables 객체에 저장합니다. 이 필드는 통화 레코드와 함께 보존됩니다. 통화 기록 및 웹훅에 보존해도 적절한 정보만 전송하십시오.

기존 프롬프트 호환성#

렌더링은 기존에 저장된 에이전트 및 A/B 변형 프롬프트, 인라인 아웃바운드 및 실시간 구성, 그리고 구성 웹훅에서 반환되는 프롬프트에도 적용됩니다. 알 수 없는 {{name}} 자리표시자는 variables가 제공되지 않은 경우에도 빈 텍스트가 됩니다. ThunderPhone에서 목록화할 수 없는 외부 제공 인라인/웹훅 프롬프트를 포함하여, 배포 전에 기존 프롬프트를 확인하십시오. Builder 마이크 및 시뮬레이션 통화에도 동일한 기본값/빈 값 동작이 적용됩니다.