Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

헤드리스 웹 SDK API 메서드

이 페이지에는 헤드리스 웹 SDK에 사용할 수 있는 API 메서드가 나와 있습니다.

회사 가치 및 메뉴를 처리하는 메서드입니다.

메서드

헤드리스 SDK는 클라이언트 인스턴스에서 호출할 수 있는 다양한 메서드를 제공합니다.

예를 들면 다음과 같습니다.

회사 및 메뉴

메서드 이름	설명
getCompany	구성된 회사 정보를 가져옵니다.
getMenus	지정된 테넌트에서 사용 가능한 모든 메뉴를 나열합니다.
getWaitTimes	메뉴에서 다양한 채널의 현재 대기 시간을 확인합니다.

getCompany

회사 이름, 지원되는 언어, 기능 설정을 포함하여 인증된 인스턴스에 대해 구성된 회사 정보를 검색합니다. 이 메서드는 내부 인스턴스 식별자 (OPTIONS.tenant)를 부작용으로 설정하므로 일반적으로 클라이언트를 구성한 후 처음으로 호출됩니다.

메서드 서명

getCompany(): Promise<CompanyResponse>

반환 값

CompanyResponse 객체를 반환합니다.

인터페이스

interface CompanyResponse {
  name: string;
  subdomain: string;
  support_email: string;
  languages: LanguageOption[];
  action_tracking: boolean;
  email_transcripts: boolean;
  message_preview: boolean;
  email_enhancement: boolean;
  display_history: boolean;
  use_recording: boolean;
  use_web: boolean;
  cobrowse_domain?: string;
}

사용 예시

try {
  const company = await client.getCompany()
} catch (error) {
  // handle error
}

getMenus

이 메서드는 인스턴스에 사용할 수 있는 모든 메뉴 항목을 나열하는 데 사용됩니다. MenuResponse.direct 필드는 결과가 직접 액세스 키 (direct.key: true)에서 가져온 것인지 아니면 사용자 수준 직접 액세스(direct.user: true)에서 가져온 것인지 호출자에게 알려줍니다. 두 가지 모두 메뉴가 표시되는 방식에 영향을 미칩니다.

메서드 서명

getMenus(key?: string, lang?: string): Promise<MenuResponse>

반환 값

MenuResponse 객체를 반환합니다.

인터페이스

interface MenuResponse {
  menus: MenuItem[];
  direct: {
    key: boolean;
    user: boolean;
    key_id: number | null;
  };
}
interface MenuItem {
  id: number;
  name?: string;
  enabled: boolean;
  redirection?: {
    option: string;
    data: string;
  };
  children?: MenuItem[];
  channels: MenuChannel[];
  deflection?: {
    enabled: boolean;
    type: string;
  };
  hidden: boolean;
}

사용 예시

try {
  const data: MenuResponse = await client.getMenus("direct_menu_key")
  console.log(data.menus)
  console.log(data.direct)
} catch (error) {
  // handle error
}

getWaitTimes

지정된 메뉴의 채팅 및 음성 통화 채널에 대한 예상 대기 시간 (초)을 검색합니다.

메서드 서명

getWaitTimes(menuId: number | string, lang?: string): Promise<WaitTimeResponse | null>

반환 값

WaitTimeResponse 객체 또는 null를 반환합니다.

인터페이스

interface WaitTimeResponse {
  chat: number;
  voice_call: number;
}

사용 예시

try {
  const data = await client.getWaitTimes(123)
} catch (error) {
  // handle error
}

통화

이름	설명
`createCall`	즉석 통화 또는 예약된 통화를 만듭니다.
`loadCall`	특정 통화 ID에서 정보를 가져옵니다.
`cancelCall`	지정된 통화 ID로 통화를 취소합니다.
`getTimeSlots`	특정 메뉴에 대해 예약된 통화에 사용할 수 있는 시간대를 가져옵니다.
`fetchTimeSlotAvailability`	특정 메뉴에 사용할 수 있는 시간대가 있는지 확인합니다.

createCall

지정된 메뉴에 대한 새 통화를 만듭니다. scheduled_at 필드가 제공되는지 여부에 따라 즉시 통화 또는 예약된 통화일 수 있습니다. 호출 유형 (web_instant_call 및 web_scheduled_call)은 scheduled_at의 존재 여부에 따라 자동으로 결정됩니다. reschedule_call_id는 호출 본문과 별도로 요청의 최상위 수준에서 전송됩니다. 응답의 menu_id는 API의 selected_menu.id에서 정규화됩니다.

메서드 서명

createCall(menuId: number | string, data: CallRequest): Promise<CallResponse>

반환 값

CallResponse 객체를 반환합니다.

인터페이스

interface CallRequest {
  phone_number: string;
  lang?: string;
  scheduled_at?: string;
  ticket_id?: string;
  email?: string;
  recording_permission?: "recording_permission_not_asked" | "recording_permission_granted" | "recording_permission_denied";
  custom_data?: {
    signed?: string;
    unsigned?: Record<string, any>;
  };
  reschedule_call_id?: number;
}

사용 예시

try {
 const call = await client.createCall(123, { phone_number: '+12345678' })
} catch (error) {
 // handle error
}

loadCall

loadCall 메서드는 ID로 식별되는 특정 통화에 대한 정보를 가져옵니다.

메서드 서명

loadCall(callId: number | string): Promise<CallResponse>

반환 값

CallResponse 객체를 반환합니다.

인터페이스

interface CallResponse {
 id: number;
 lang: string;
 menu_id: number;
 status: string;
 type: string;
 scheduled_at?: string;
 recording_permitted: boolean;
 survey_enabled: boolean;
 created_at: string;
 menus: {
   id: number;
   name: string;
 }[];
}

사용 예시

try {
 const call = await client.loadCall(1234)
} catch (error) {
 // handle error
}

cancelCall

ID로 기존 통화를 취소합니다. 일반적으로 아직 걸지 않은 예약된 통화를 취소하는 데 사용됩니다.

메서드 서명

cancelCall(callId: number | string): Promise<CallResponse>

반환 값

CallResponse 객체를 반환합니다.

인터페이스

interface CallResponse {
 id: number;
 lang: string;
 menu_id: number;
 status: string;
 type: string;
 scheduled_at?: string;
 recording_permitted: boolean;
 survey_enabled: boolean;
 created_at: string;
 menus: {
   id: number;
   name: string;
 }[];
}

사용 예시

try {
 const response = await client.cancelCall(1234)
} catch (error) {
 // handle error
}

getTimeSlots

특정 메뉴에서 예약된 통화에 사용할 수 있는 시간대를 가져옵니다. GetTimeSlotsRequest 옵션 객체로 호출되면 rescheduleCallId를 사용하여 기존 통화의 일정을 변경할 수 있습니다. 지원 중단된 lang 문자열 서명은 계속 지원되며 lang만 채워진 동일한 엔드포인트로 라우팅됩니다. 시간대 문자열 배열을 반환합니다.

메서드 서명

getTimeSlots(menuId: number | string, options?: GetTimeSlotsRequest): Promise<string[]>

반환 값

문자열 배열 (시간대)을 반환합니다.

인터페이스

interface GetTimeSlotsRequest {
 lang?: string;
 rescheduleCallId?: number;          // ID of an existing call being rescheduled
}

사용 예시

// New options-based signature (recommended)
try {
 const slots = await client.getTimeSlots(123, {
   lang: 'en',
   rescheduleCallId: 98765, // optional: pass when rescheduling an existing call
 })
} catch (error) {
 // handle error
}
// Deprecated signature (still supported)
try {
 const slots = await client.getTimeSlots(123, 'en')
} catch (error) {
 // handle error
}

fetchTimeSlotAvailability

이 메서드는 전체 시간대 목록을 가져오지 않고 특정 메뉴에 사용할 수 있는 시간대가 있는지 확인합니다. UI에서 예약 옵션을 조건부로 표시하는 데 유용합니다.

범위

fetchTimeSlotAvailability은 예약된 음성 통화 (콜백) 약속에만 적용됩니다. 채팅, 이메일 또는 즉시 통화 채널에 대한 정보는 반환되지 않습니다. 제공된 메뉴는 예약된 음성 통화를 지원하도록 구성되어야 하며, 운영 시간이 정의되어 있고 해당 메뉴에 최소 한 명의 상담사가 대기 중이어야 합니다.

일반적인 사용 사례:

슬롯이 있는 경우에만 '콜백 예약' 클릭 유도 문구를 조건부로 렌더링합니다.
사용 가능한 슬롯이 없는 경우 전체 getTimeSlots 통화 비용을 지불하지 않고 디플렉션 흐름 (예: 이메일, 업무 시간 외 메시지)으로 분기합니다.
rescheduleCallId를 사용하여 getTimeSlots를 호출하기 전에 일정 변경 작업을 프리플라이트합니다.

메서드 서명

fetchTimeSlotAvailability(menuId: number | string, lang?: string): Promise<boolean>

반환 값

시간대가 있으면 true를 반환하고, 그렇지 않으면 false를 반환합니다.

사용 예시

try {
 const isAvailable = await client.fetchTimeSlotAvailability(123, 'en')
 if (isAvailable) {
   // Show scheduling UI
 }
} catch (error) {
 // handle error
}

채팅

이름	설명
`createChat`	새 채팅을 만듭니다.
`loadChat`	지정된 채팅 ID로 채팅을 가져옵니다.
`loadOngoingChat`	진행 중인 채팅을 로드하려고 시도합니다.
`resumeChat`	지정된 채팅 ID로 종료된 채팅을 재개합니다.
`finishChat`	현재 채팅의 상태를 완료로 설정합니다.
`destroyChat`	`finishChat`를 호출하고 현재 채팅을 소멸시킵니다.
`fetchMessages`	이전 메시지를 가져옵니다. 실패 시 `[]`를 반환합니다.
`sendTextMessage`	문자 메시지를 전송합니다.
`sendFileMessage`	파일 메시지를 전송합니다. 업로드 실패 시 `-1`를 반환합니다.
`sendPreviewMessage`	미리보기 메시지를 전송합니다.
`getChatDeflection`	채팅 전환 구성을 가져옵니다.
`sendChatTranscripts`	지정된 이메일로 채팅 스크립트를 전송합니다.
`downloadChatTranscript`	채팅 스크립트를 다운로드합니다.
`getPdfStatus`	스크립트의 PDF 상태를 가져옵니다.
`getChatSurvey`	채팅 설문조사 질문을 가져옵니다.
`sendChatSurvey`	설문조사에서 사용자 의견을 전송합니다.
`sendChatRate`	채팅에 관한 사용자 의견을 보냅니다.
`escalateChat`	가상 에이전트에서 상담사로 채팅을 에스컬레이션합니다.
`trackChatEscalation`	채팅 에스컬레이션 이벤트를 추적합니다.
`trackChatEndUserEvent`	최종 사용자 이벤트를 추적합니다.
`getChatHistory`	지정된 채팅의 기록을 가져옵니다.

채팅 확인

체크인은 상담사와 연결하기 전에 소비자에게 준비가 되었는지 확인하는 기능입니다. 이 섹션에서는 이러한 환경을 구현하기 위한 헤드리스 웹 SDK 메서드를 설명합니다. 체크인이란 무엇인지, 어떻게 사용 설정하고 구성하는지 (대기 시간, 제한 시간, 대기열 위치, 다시 참여 동작), 보고에 관한 자세한 내용은 채팅 체크인을 참고하세요.

이름	설명
`checkIn`	사용자가 대기열에 있는지 확인하기 위해 서버에 신호를 보냅니다.
`exitCheckIn`	체크인 대기열에서 사용자를 삭제합니다.
`notifyCheckInState`	체크인 모달 공개 상태를 백엔드에 알립니다.
`rejoinChat`	체크인 확인에 실패한 후 사용자를 다시 대기열에 배치합니다.
`trackCheckInEvent`	UI에서 체크인 이벤트가 트리거되면 백엔드에 신호를 보냅니다.

`checkIn`

체크인 기간 동안 소비자가 있고 상담사와 연결할 준비가 되었음을 나타내는 확인 신호를 서버에 전송합니다. 서버에서 확인한 후 채팅의 check_in_status를 로컬에서 업데이트합니다. chat.checkInRequested 이벤트에 대한 응답으로 사용합니다.

메서드 서명

checkIn(): Promise<CheckInResponse>

반환 값

CheckInResponse 객체를 반환합니다.

인터페이스

interface CheckInResponse {
 chat_id: number;
 check_in_status: CheckInStatus;
 check_in_at?: string;
}
enum CheckInStatus {
 CONFIRMED = 'confirmed',
 EXITED = 'exited',
 PENDING = 'pending',
 REQUESTED = 'requested',
 SKIPPED = 'skipped',
 TIMED_OUT = 'timed_out',
}

사용 예시

try {
 const response = await client.checkIn()
} catch (error) {
 // handle error
}

`exitCheckIn`

소비자가 체크인 대기열에서 나가기로 선택했음을 서버에 알립니다. check_in_status를 로컬에서 업데이트합니다. 이 메서드를 호출한 후에는 소비자가 현재 체크인 주기에 상담사 연결을 받지 않습니다.

메서드 서명

exitCheckIn(): Promise<CheckInResponse>

반환 값

CheckInResponse 객체를 반환합니다.

인터페이스

interface CheckInResponse {
 chat_id: number;
 check_in_status: CheckInStatus;
 check_in_at?: string;
}
enum CheckInStatus {
 CONFIRMED = 'confirmed',
 EXITED = 'exited',
 PENDING = 'pending',
 REQUESTED = 'requested',
 SKIPPED = 'skipped',
 TIMED_OUT = 'timed_out',
}

사용 예시

try {
 const response = await client.exitCheckIn()
} catch (error) {
 // handle error
}

`notifyCheckInState`

체크인 모달의 현재 공개 상태(위젯이 최소화되었는지 또는 브라우저 탭이 비활성 상태인지)를 서버에 알립니다. 서버는 이 값을 사용하여 체크인 시점을 결정합니다. chat.checkInRequested 이벤트가 활성 상태인 동안 위젯의 공개 상태 또는 탭 포커스가 변경될 때마다 호출해야 합니다.

메서드 서명

notifyCheckInState(data: CheckInVisibilityStateRequest): Promise<void>

인터페이스

interface CheckInVisibilityStateRequest {
 widget_minimized?: boolean;
 tab_inactive?: boolean;
}

사용 예시

try {
 const visibilityState = {
   widget_minimized: true,
   tab_inactive: false,
 }
 await client.notifyCheckInState(visibilityState)
} catch (error) {
 // handle error
}

`rejoinChat`

소비자가 할당된 시간 내에 체크인을 확인하지 못한 경우 소비자를 다시 대기열에 배치합니다. check_in_status를 로컬에서 업데이트합니다. 소비자가 계속 연결하기를 원하는 경우 chat.checkInTimedOut 이벤트에 대한 응답으로 사용합니다.

메서드 서명

rejoinChat(): Promise<CheckInResponse>

반환 값: CheckInResponse 객체를 반환합니다.

인터페이스

interface CheckInResponse {
 chat_id: number;
 check_in_status: CheckInStatus;
 check_in_at?: string;
}
enum CheckInStatus {
 CONFIRMED = 'confirmed',
 EXITED = 'exited',
 PENDING = 'pending',
 REQUESTED = 'requested',
 SKIPPED = 'skipped',
 TIMED_OUT = 'timed_out',
}

사용 예시

try {
 const response = await client.rejoinChat()
} catch (error) {
 // handle error
}

`trackCheckInEvent`

체크인 모달이 소비자에게 표시되었음을 서버에 알립니다. chat.checkInRequested에 대한 응답으로 체크인 UI를 표시한 직후에 이 메서드를 한 번 호출합니다. 서버는 이 정보를 체크인 표시율에 관한 운영 분석에 사용합니다. 호출은 내부적으로 대기되고 거부할 수 있는 Promise<void>를 반환하므로 다음 예와 같이 try/catch로 래핑합니다.

메서드 서명

trackCheckInEvent(): Promise<void>

사용 예시

try {
 await client.trackCheckInEvent()
} catch (error) {
 // handle error
}

getMessageAttachment

특정 채팅 메시지와 연결된 적격 첨부파일을 가져옵니다. 메시지가 최종 사용자가 아닌 사용자 ($userType !== 'end_user')가 전송하고 지원되는 첨부파일 유형 (사진, 동영상, 오디오, 문서)인 경우에만 가져옵니다. media_id가 없는 메시지뿐만 아니라 두 조건을 모두 충족하지 않는 메시지에 대해 null를 반환합니다. 가져온 파일을 검색 후 채팅의 로컬 미디어 캐시에 저장합니다.

메서드 서명

getMessageAttachment(message: MessageResponse): Promise<File | null>

반환 값

발견되면 File 객체를 반환하고, 해당하지 않으면 null을 반환합니다.

사용 예시

try {
 const file = await client.getMessageAttachment(message)
} catch (error) {
 // handle error
}

createChat

지정된 메뉴의 새 채팅 세션을 만듭니다. 원하는 경우 언어, 인사말 메시지, 트리거 ID, 티켓 ID, 채팅과 함께 전송할 고객 데이터를 지정할 수 있습니다.

초기 API 호출 후 이 메서드는 provider_channel_id를 사용할 수 있거나 채팅이 취소되거나 완료될 때까지 서버를 폴링합니다. 제공업체 채널을 사용할 수 있게 되면 이 메서드는 실시간 제공업체에 대한 연결을 시작합니다. 프로미스가 해결될 때 연결이 아직 완료되지 않았을 수 있습니다. chat.connectedMessages 이벤트를 수신 대기하여 연결 및 초기 메시지 검색이 완료된 시점을 확인하세요.

메서드 서명

createChat(menuId: number | string, data: ChatRequest): Promise<Chat>

반환 값

Chat 인스턴스를 반환합니다.

인터페이스

interface ChatRequest {
  lang?: string;
  trigger_id?: string;
  ticket_id?: string;
  email?: string;
  greeting?: string;
  cobrowsable?: boolean;
  custom_data?: {
    signed?: string;
    unsigned?: Record<string, any>;
  };
}

사용 예시

try {
 const chat = await client.createChat(123, { lang: 'en' })
} catch (error) {
 // handle error
}

loadChat

ID로 기존 채팅 세션을 가져옵니다.

로드된 채팅이 더 이상 진행 중이 아니면 이 메서드는 로컬 저장소에서 저장된 채팅 ID와 공동 탐색 nonce를 지웁니다. 또한 오류가 발생할 때도 이 작업을 수행하므로 호출자는 로드 실패 후 저장소 정리를 수동으로 처리할 필요가 없습니다.

메서드 서명

loadChat(chatId: number | string): Promise<Chat>

반환 값

Chat 인스턴스를 반환합니다.

사용 예시

try {
 const chat = await client.loadChat(1234)
} catch (error) {
 // handle error
}

loadOngoingChat

현재 진행 중인 채팅 세션이 있는 경우 이를 로드하려고 시도합니다. 진행 중인 채팅이 없으면 null를 반환합니다.

메서드 서명

loadOngoingChat(): Promise<Chat | null>

반환 값

진행 중인 채팅이 있는 경우 Chat 인스턴스를 반환하고, 진행 중인 채팅이 없는 경우 null을 반환합니다. 채팅이 진행 중이 아니면 저장소 값을 삭제합니다.

사용 예시

try {
 const chat = await client.loadOngoingChat()
} catch (error) {
 // handle error
}

resumeChat

이전에 종료된 채팅 세션을 ID로 재개하여 소비자가 대화를 계속할 수 있도록 합니다.

클라이언트가 이미 동일한 ID의 채팅에 대한 참조를 보유하고 있는 경우 이 메서드는 단락됩니다. 즉, 새 인스턴스를 가져오는 대신 기존 인스턴스에서 상태를 queued로 패치합니다. ID가 일치하지 않으면 새 Chat 인스턴스가 생성되고 등록됩니다.

메서드 서명

resumeChat(chatId: number | string): Promise<Chat>

반환 값

Chat 인스턴스를 반환합니다.

사용 예시

try {
 const chat = await client.resumeChat(1234)
} catch (error) {
 // handle error
}

finishChat

현재 채팅 세션의 상태를 완료로 설정합니다. 이렇게 하면 소비자 측에서 채팅이 종료됩니다.

채팅이 실시간 제공업체에 연결되어 있고 PATCH 후 종료 상태인 경우 이 메서드는 제공업체와의 연결도 끊습니다. 채팅을 정상적으로 종료하는 것만이 목표인 경우 호출자는 destroyChat를 호출할 필요가 없습니다.

메서드 서명

finishChat(): Promise<void>

사용 예시

try {
 await client.finishChat()
} catch (error) {
 // handle error
}

destroyChat

현재 채팅 세션을 종료하고 소멸시켜 모든 내부 상태를 정리합니다. 이렇게 하면 내부적으로 finishChat가 호출된 후 채팅 인스턴스가 해제됩니다. 채팅을 완료하기 전에 이 메서드는 해체 중에 메시지를 처리하지 않도록 채팅을 음소거합니다 (수신되는 실시간 이벤트 억제). 채팅이 소멸된 후 내부 추적기 ID를 삭제합니다.

메서드 서명

destroyChat(): Promise<void>

사용 예시

try {
 await client.destroyChat()
} catch (error) {
 // handle error
}

fetchMessages

실시간 제공업체에서 현재 채팅 세션의 메시지 기록을 가져옵니다. 채팅이 연결된 후에 호출해야 합니다. 채팅이 연결되기 전에 호출하면 예외를 발생시키는 대신 빈 배열을 반환합니다. document 유형 메시지의 문서 URL을 자동으로 가져와 응답에 병합합니다. server_message 유형 메시지의 경우 태스크 가상 에이전트 메시지 콘텐츠를 가져와 인라인으로 형식을 지정합니다. 실패 시 예외를 발생시키는 대신 빈 배열을 반환합니다.

메서드 서명

fetchMessages(): Promise<MessageResponse[]>

반환 값

MessageResponse 배열을 반환합니다. 실패 시 빈 배열을 반환합니다.

인터페이스

interface MessageResponse {
  $index: number;
  $sid: string;
  $timestamp: Date;
  $userType: string;
  $userId: number;
  type: string;
  content?: string;
  event?: string;
  file?: File;
  media_id?: number;
  groupMessageId?: number;
  document?: {
    url: string;
  };
  unredacted?: string;
  buttons?: {
    title: string;
  }[];
  message?: { messages: string[], type };
  signature?: string,
  form?: {
    id: number,
    form_type: string,
    name: string,
    title: string,
    subtitle: string,
    external_form_id: string,
    smart_action_id: number,
    image: string
  }

  // allow extra parameters
  [key: string]: unknown;
}

사용 예시

const messages = await client.fetchMessages()

sendTextMessage

현재 채팅 세션에서 문자 메시지를 보냅니다.

이 메서드는 전송하기 전에 원시 콘텐츠를 정제하고 결과가 비어 있으면 조기 반환 (노옵스)합니다. 채팅이 태스크 가상 에이전트 흐름 (inTask)에 있는 경우 메시지는 일반 채널 대신 태스크 가상 에이전트 엔드포인트를 통해 라우팅됩니다. 서버 측 수정이 사용 설정된 경우 메시지는 실시간 제공업체를 직접 통하지 않고 서버 엔드포인트를 사용하여 전송됩니다.

메서드 서명

sendTextMessage(rawContent: string): Promise<void>

사용 예시

try {
 await client.sendTextMessage("hello world")
} catch (error) {
 // handle error
}

sendFileMessage

서버에서 미리 서명된 클라우드 스토리지 URL을 가져오고, 해당 URL에 파일을 직접 업로드한 후, 서버에 업로드를 다시 확인하는 3단계 프로세스를 통해 현재 채팅 세션에 파일을 업로드합니다. 업로드 경로는 파일의 MIME 유형에 따라 자동으로 결정됩니다. 이미지는 사진 메시지로, 동영상은 동영상 메시지로 전송되며 다른 파일 형식은 MIME 유형에 따라 라우팅됩니다. 성공 시 메시지 ID를 반환하고 실패 시 -1를 반환합니다.

메서드 서명

sendFileMessage(file: File): Promise<number>

반환 값

업로드에 실패하면 메시지 ID 또는 -1을 반환합니다. 하지만 후속 메시지 전송은 여전히 거부될 수 있으므로 (예: ChatEndedError) -1를 확인하는 것 외에도 try/catch에서 호출을 래핑합니다.

사용 예시

const input = document.querySelector('input[type="file"]')
const file = input.files[0]
try {
  const id = await client.sendFileMessage(file)
  if (id === -1) {
    // handle upload failure
  }
} catch (error) {
  // handle message-send failure
}

sendPreviewMessage

현재 채팅 세션에서 미리보기 메시지를 전송합니다. 미리보기 메시지는 일반적으로 메시지가 제출되기 전에 소비자가 입력하는 내용을 상담사에게 표시하는 데 사용됩니다. 채팅 상태에서 redaction_enabled 및 agent_incoming_ha_enabled가 모두 true인 경우 미리보기는 실시간 제공업체 채널이 아닌 서버 엔드포인트(POST /chats/{id}/redact_messages)를 통해 전송됩니다.

메서드 서명

sendPreviewMessage(content: string): Promise<void>

사용 예시

try {
 await client.sendPreviewMessage('preview content')
} catch (error) {
 // handle error
}

getChatDeflection

현재 채팅 세션의 채팅 전환 구성(전환 사용 설정 여부, 대기 시간 기준, 사용 가능한 전환 옵션 포함)을 검색합니다.

채팅에 편향이 사용 설정되지 않은 경우 null을 반환합니다 (서버 응답의 enabled 필드가 거짓임). 호출자는 응답을 읽기 전에 null을 확인해야 합니다.

메서드 서명

getChatDeflection(): Promise<ChatDeflectionResponse | null>

반환 값

채팅에 디플렉션이 사용 설정되지 않은 경우 ChatDeflectionResponse 객체 또는 null를 반환합니다.

인터페이스

interface ChatDeflectionResponse {
 enabled: boolean;
 threshold: number;
 email: boolean;
 keep_waiting: boolean;
 external_deflection_links: {
   enabled: boolean;
   ids: number[];
 };
}

사용 예시

try {
 const deflection = await client.getChatDeflection()
} catch (error) {
 // handle error
}

sendChatTranscripts

현재 채팅 스크립트를 지정된 이메일 주소로 전송합니다.

메서드 서명

sendChatTranscripts(emails: string[]): Promise<void>

사용 예시

try {
 await client.sendChatTranscripts([
   "name1@example.com",
   "name2@example.com",
 ])
} catch (error) {
 // handle error
}

downloadChatTranscript

현재 채팅 스크립트를 PDF로 다운로드합니다. getPdfStatus와 함께 사용하여 생성 진행 상황을 추적할 수 있는 스크립트 작성 객체를 반환합니다.

메서드 서명

downloadChatTranscript(): Promise<GenerateTranscriptResponse>

반환 값

스크립트 객체를 반환합니다.

인터페이스

interface GenerateTranscriptResponse {
 status: string;
 chat_transcript_id: number;
}

사용 예시

try {
 const resp = await client.downloadChatTranscript()
} catch (error) {
 // handle error
}

getPdfStatus

이전에 요청한 채팅 스크립트 PDF의 생성 상태를 확인합니다. downloadChatTranscript에서 반환된 chat_transcript_id를 사용하여 완료를 폴링합니다.

메서드 서명

getPdfStatus(id: number): Promise<RequestReturn>

반환 값

PDF 상태 객체를 반환합니다.

인터페이스

interface RequestReturn {
   //...
   headers,
   data: PdfStatusResponse,
 }


 interface PdfStatusResponse {
   status: string;
   body?: File;
   failed_reason?: string;
 }

사용 예시

const response = await client.getPdfStatus(pdfId)
// check header for status
const status = response.headers['x-transcript-status'];
// otherwise use status on data
const data = response.data
console.log(data.status)

getChatSurvey

현재 채팅 세션에 구성된 채팅 후 설문조사 질문을 가져옵니다. 설문조사는 채팅이 종료된 후 소비자에게 표시됩니다.

메서드 서명

getChatSurvey(): Promise<ChatSurveyResponse | null>

반환 값

ChatSurveyResponse 객체 또는 null을 반환합니다.

인터페이스

interface QuestionItem {
 id: number;
 type: "csat" | "star" | "free-form" | "scale" | "enumeration";
 display_text: string;
 name?: string;
 is_csat?: boolean;
 position?: number;
 valid_answers?: {
   key: string;
   value: string;
 }[]
}
interface ChatSurveyResponse {
 id?: number;
 lang?: string;
 sign_off_display_text: string;
 questions: QuestionItem[];
}

사용 예시

try {
 const data = await client.getChatSurvey()
 if (data) {
   console.log(data.questions)
 }
} catch (error) {
 // handle error
}

sendChatSurvey

소비자의 답변을 채팅 후 설문조사에 제출합니다. 각 답변은 질문 ID로 키가 지정됩니다.

메서드 서명

sendChatSurvey(answers: SurveyAnswers): Promise<void>

인터페이스

interface SurveyAnswers {
 [question_id: string]: number | string;
}

사용 예시

try {
 await client.sendChatSurvey({
   123: "a",
   231: "b",
 })
} catch (error) {
 // handle error
}

sendChatRate

채팅 세션에 대한 소비자의 평점과 의견(선택사항)을 제출합니다. 채팅 후 의견 유형이 전체 설문조사가 아닌 평점인 경우에 사용됩니다.

메서드 서명

sendChatRate(data: RateRequest): Promise<void>

인터페이스

interface RateRequest {
 rating: number;
 feedback?: string;
}

사용 예시

try {
 await client.sendChatRate({
   rating: 5,
   feedback: "Very good service",
 })
} catch (error) {
 // handle error
}

escalateChat

현재 채팅을 가상 에이전트에서 상담사에게 에스컬레이션합니다.

메서드 서명

escalateChat(data?: EscalateRequest): Promise<void>

인터페이스

interface EscalateRequest {
 force_escalate: boolean;
 menu_id: number;
 lang: string;
}

사용 예시

try {
 // Escalate to a specific menu in a given language
 await client.escalateChat({
   force_escalate: true,
   menu_id: 123,
   lang: 'en',
 })
} catch (error) {
 // handle error
}
// Or, escalate without arguments to use defaults
try {
 await client.escalateChat()
} catch (error) {
 // handle error
}

trackChatEscalation

채팅 에스컬레이션 이벤트를 추적하여 에스컬레이션 ID와 에스컬레이션된 채널을 기록합니다.

메서드 서명

trackChatEscalation(escalationId: number, channel: string): Promise<void>

사용 예시

try {
 await client.trackChatEscalation(escalationId, channel)
} catch (error) {
 // handle error
}

trackChatEndUserEvent

채팅 세션 중에 커스텀 최종 사용자 이벤트를 추적합니다. 이 이벤트는 분석에 사용하거나 백엔드 워크플로를 트리거하는 데 사용할 수 있습니다. data 객체에 end_user_name가 포함되지 않고 인증된 사용자 프로필에 이름이 있는 경우 요청이 전송되기 전에 자동으로 채워집니다.

메서드 서명

trackChatEndUserEvent(data: ChatEndUserEventRequest): Promise<void>

반환 값

void를 반환합니다.

인터페이스

interface ChatEndUserEventRequest {
  event: {
    name: string;
    payload: Record<string, string>;
  };
  end_user_name?: string;
}

사용 예시

try {
 await client.trackChatEndUserEvent({
   event: {
     name: 'add_to_cart',
     payload: {
       product_id: 'sku-1234',
       quantity: '2',
     },
   },
   // end_user_name is auto-populated from the authenticated user
   // profile if omitted
 })
} catch (error) {
 // handle error
}

getChatHistory

메시지 콘텐츠 및 메타데이터를 포함하여 소비자의 이전 채팅 기록을 검색합니다. 결과는 페이지로 나뉩니다. 페이지 1은 최대 2개의 채팅을 반환하고 이후 페이지는 각각 1개의 채팅을 반환합니다. 이 비대칭 페이지로 나누기는 의도적인 것이며 첫 번째 호출에서 인접한 기록 컨텍스트를 미리 로드할 수 있습니다.

메서드 서명

getChatHistory(page?: number): Promise<ChatHistoryResponse | null>

반환 값

ChatHistoryResponse 객체 또는 null를 반환합니다.

인터페이스

interface ChatHistoryItem {
 comm_id: number;
 assigned_at: string;
 comm_type: string;
 timezone: string;
 entries: MessageResponse[];
 [key: string]: unknown;
}
interface ChatHistoryResponse {
 chats: ChatHistoryItem[];
 missing_chat_ids: number[];
 pagination: {
   next_page: number;
   per_page: number;
 }
}

사용 예시

try {
 const data = await client.getChatHistory(1) // page defaults to 1 if omitted
 console.log(data)
} catch (error) {
 console.log(error)
}

이메일

이름	설명
`createEmail`	지정된 메뉴 ID의 이메일 채널로 이메일을 보냅니다.
`getProhibitedFileTypes`	이메일 첨부파일에 허용되지 않는 파일 형식을 가져옵니다.

createEmail

지정된 메뉴와 연결된 이메일 채널로 이메일 메시지를 보냅니다. 소비자는 이름, 이메일 주소, 메일 본문, 선택적 파일 첨부파일을 포함할 수 있습니다.

메서드 서명

createEmail(menuId: number | string, data: EmailRequest): Promise<EmailResponse>

반환 값

실패 또는 성공 시 EmailResponse 객체를 반환합니다.

인터페이스

interface EmailRequest {
 name?: string;
 email: string;
 content: string;
 lang?: string;
 files?: File[];
 recaptcha?: string;
}
interface EmailResponse {
 id: number;
 type: string;
 status: string;
 fail_reason: string;
 attachment_count: number;
}

사용 예시

try {
 await client.createEmail(123, {
   lang: "en",
   name: "User name",
   email: "name@example.com",
   content: "description of the question",
   files: input.files,
 })
} catch (error) {
 console.log(error.message)
}

getProhibitedFileTypes

관리자가 구성한 대로 이메일 첨부파일로 허용되지 않는 파일 형식 목록을 가져옵니다.

메서드 서명

getProhibitedFileTypes(): Promise<FileTypeItem[]>

반환 값

FileTypeItem 배열을 반환합니다.

인터페이스

interface FileTypeItem {
 extension: string;
 description: string;
}

사용 예시

try {
 const types = await client.getProhibitedFileTypes()
} catch (error) {
 // handle error
}

화면 공유

이름	설명
`createCobrowseCode`	화면 공유 코드를 생성합니다.
`startCobrowse`	공동 탐색 세션을 요청합니다.
`restoreCobrowseSession`	브라우저 창이 다시 열린 후 공동 탐색 세션을 복원합니다.

createCobrowseCode

상담사와 공유하여 세션을 시작할 수 있는 고유한 공동 탐색 (화면 공유) 세션 코드를 생성합니다. 아직 초기화되지 않은 경우 화면 공유 클라이언트를 초기화합니다. 호출할 때마다 새 nonce를 생성하는 대신 저장소의 기존 nonce를 재사용하므로 페이지 로드 전반에서 동일한 세션 코드를 가져올 수 있습니다.

메서드 서명

createCobrowseCode(lang?: string, customData?: Record<string, string>): Promise<string>

반환 값

실패 시 공동 탐색 코드 문자열 또는 빈 문자열 ('')을 반환합니다.

사용 예시

const code = await client.createCobrowseCode()
// 123456

startCobrowse

활성 채팅 중에 최종 사용자 측에서 공동 탐색 (화면 공유) 세션 시작을 요청합니다.

메서드 서명

startCobrowse(from?: string): Promise<void>

사용 예시

try {
 await client.startCobrowse()
} catch (error) {
 // handle error
}

restoreCobrowseSession

브라우저 창이 다시 열리거나 위젯이 새로고침된 후 이전에 활성 상태였던 공동 탐색 세션을 복원하려고 시도합니다.

메서드 서명

restoreCobrowseSession(): Promise<void>

반환 값

Promise<void>를 반환합니다. 이 메서드는 클라이언트 옵션에서 공동 탐색이 사용 설정되지 않았거나 저장소에 이전 공동 탐색 세션이 없는 경우 노옵스 (오류 없이 즉시 반환)입니다.

사용 예시

// Safe to call unconditionally - will no-op if cobrowse is not enabled
// or if no previous session exists
await client.restoreCobrowseSession()

세션 후 가상 에이전트

이름	설명
`updatePostSession`	진행 중인 채팅의 세션 후 상태를 설정합니다.

updatePostSession

이 메서드는 진행 중인 채팅의 세션 후 가상 에이전트 상태를 업데이트하는 데 사용됩니다.

진행 중인 채팅의 세션 후 가상 에이전트 상태를 업데이트합니다. 이를 사용하여 세션 후 가상 에이전트 흐름의 준비, 진행 상황 또는 완료를 알립니다.
postSessionStatus가 FINISHED 또는 WAITING인 경우 노옵스(no-ops)로 즉시 반환됩니다. 이러한 전환은 내부적으로 처리됩니다.
400 응답의 IN_PROGRESS 상태에 대한 내부 재시도 로직이 있으므로 호출자가 이 경우에 대한 자체 재시도를 구현할 필요가 없습니다.

메서드 서명

updatePostSession(postSessionStatus: PostSessionStatus, optInSelection?: boolean): Promise<void>

인터페이스

enum PostSessionStatus {
 READY = 'ready',
 IN_PROGRESS = 'in_progress',
 WAITING = 'waiting',
 FINISHED = 'finished',
}

사용 예시

try {
 // Without opt-in selection
 await client.updatePostSession(PostSessionStatus.READY)
 // With opt-in selection
 await client.updatePostSession(PostSessionStatus.READY, true)
} catch (error) {
 // handle error (e.g., show a notification to the user)
}

디버깅

이름	설명
`getLogs`	SDK에서 내부 디버그 로그를 가져옵니다.
`printLogs`	브라우저 콘솔에 내부 디버그 로그를 출력합니다.

getLogs

브리지 수준 로그와 루트 수준 로그를 모두 포함하여 SDK에서 수집한 내부 디버그 로그를 검색합니다. 통합 문제를 해결하는 데 유용합니다.

메서드 서명

getLogs(): Promise<{ bridgeLogs: LogHistoryData[], rootLogs: LogHistoryData[] }>

반환 값

LogHistoryData 배열 두 개가 포함된 객체를 반환합니다.

인터페이스

interface LogHistoryData {
 date: string;
 channel: string;
 level: string;
 args: any[];
}

세부사항

각 LogHistoryData 항목은 단일 로그 이벤트를 캡처합니다.

date - 이벤트의 ISO 8601 타임스탬프입니다.
channel - 이벤트를 내보낸 SDK 모듈 (예: 최상위 클라이언트, 채팅 레이어, 공동 탐색 레이어, 실시간 제공업체)
level - 로그 심각도: debug, info, warn 또는 error
args - 로그 호출로 캡처된 원시 인수입니다.

예시 항목:

{
 "date": "2026-05-08T14:02:13.412Z",
 "channel": "Provider",
 "level": "info",
 "args": ["chat connected", { "chatId": 4421 }]
}

정확한 채널 및 메시지 콘텐츠 집합은 SDK 출시 사이에 변경될 수 있습니다. 로그를 안정적인 파싱 대상이 아닌 디버깅 보조 도구로 취급합니다. 특정 채널 이름이나 메시지 문자열에 의존하는 프로덕션 로직을 빌드하지 마세요.

범위 및 권장 사용법

getLogs는 헤드리스 웹 SDK 자체의 통합 문제를 진단하는 데 도움이 되는 SDK 내부 레코드를 반환합니다. 기본 사용 사례는 지원 진단입니다. 최종 사용자가 문제를 신고하면 애플리케이션이 getLogs 결과를 캡처하여 CCAI Platform에 전송된 지원 티켓에 연결할 수 있습니다.

반환된 로그에는 다음이 포함되지 않습니다.

호스트 페이지의 애플리케이션 원격 분석, 비즈니스 이벤트 또는 사용자 탐색
브라우저가 SDK에 표시하지 않는 네트워크 오류 (예: CORS, 혼합 콘텐츠 또는 인증서 오류)
SDK에 반환된 HTTP 상태를 초과하는 서버 측 요청 trace 또는 백엔드 세부정보

getLogs는 자체 모니터링 가능성 도구를 대체하지 않습니다. SDK를 다음 항목과 페어링하는 것이 좋습니다.

브라우저 측 오류/RUM 추적기 (Sentry, Datadog Browser RUM, New Relic Browser 또는 이와 동등한 도구)
인증 엔드포인트 (SDK가 호출하는 authenticate 콜백)의 서버 측 로깅
채팅 수명 주기 신호를 자체 원격 분석 파이프라인으로 전달해야 하는 경우 chat.disconnected, chat.timeout, chat.ended의 애플리케이션 수준 리스너

사용 예시

try {
 const { bridgeLogs, rootLogs } = await client.getLogs()
 console.log('Bridge logs:', bridgeLogs)
 console.log('Root logs:', rootLogs)
} catch (error) {
 // handle error
}

printLogs

모든 내부 디버그 로그를 브라우저 콘솔에 직접 출력합니다. 이 메서드는 내부적으로 getLogs()를 호출하고 출력 형식을 지정하는 편의 메서드입니다.

메서드 서명

printLogs(): Promise<void>

사용 예시

try {
 await client.printLogs()
} catch (error) {
 // handle error
}

기타

이름	설명
`runTrigger`	실행해야 하는 사전 트리거를 확인합니다.
`getAfterHourMessage`	영업시간 외 전환 메시지를 받습니다.

runTrigger

구성된 사전 대응 트리거를 반복하고 조건 (URL 키워드, 페이지 방문 횟수, 체류 시간, 방문자 유형)이 충족되는 트리거에 대해 제공된 콜백을 호출합니다.

메서드 서명

runTrigger(cb: (trigger: TriggerItem) => void): Promise<void>

인터페이스

interface TriggerItem {
 id: number;
 menu_id: number;
 messages: TriggerMessage[];
 keywords_included?: string[];
 keywords_included_or?: string[][];
 keywords_excluded?: string[];
 keywords_excluded_or?: string[][];
 lang?: string;
 page_visit_count: number;
 stay_time: number;
 visitor_type: string;
}
interface TriggerMessage {
 lang: string;
 text: string;
}

사용 예시

await client.runTrigger((trigger: TriggerItem) => {
 // code to run for given trigger
})

getAfterHourMessage

요청된 채널이 운영시간 외일 때 표시할 구성된 편향 메시지를 반환합니다.

메서드 서명

메서드 서명은 다음과 같습니다.

getAfterHourMessage(lang?: string): Promise<string>

반환 값

구성된 메시지가 포함된 문자열을 반환합니다.

사용 예시

try {
 const message: string = await client.getAfterHourMessage()
} catch (error) {
 // handle error
}

헤드리스 웹 SDK API 메서드 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

회사 및 메뉴

메서드

회사 및 메뉴

getCompany

메서드 서명

반환 값

인터페이스

사용 예시

getMenus

메서드 서명

반환 값

인터페이스

사용 예시

getWaitTimes

메서드 서명

반환 값

인터페이스

사용 예시

통화

createCall

메서드 서명

반환 값

인터페이스

사용 예시

loadCall

메서드 서명

반환 값

인터페이스

사용 예시

cancelCall

메서드 서명

반환 값

인터페이스

사용 예시

getTimeSlots

메서드 서명

반환 값

인터페이스

사용 예시

fetchTimeSlotAvailability

범위

메서드 서명

반환 값

사용 예시

채팅

채팅 확인

checkIn

메서드 서명

반환 값

인터페이스

사용 예시

exitCheckIn

메서드 서명

반환 값

인터페이스

사용 예시

notifyCheckInState

메서드 서명

인터페이스

사용 예시

rejoinChat

메서드 서명

인터페이스

사용 예시

trackCheckInEvent

메서드 서명

사용 예시

getMessageAttachment

메서드 서명

반환 값

사용 예시

createChat

메서드 서명

반환 값

인터페이스

사용 예시

loadChat

메서드 서명

반환 값

헤드리스 웹 SDK API 메서드

`checkIn`

`exitCheckIn`

`notifyCheckInState`

`rejoinChat`

`trackCheckInEvent`