ヘッドレス ウェブ SDK API メソッド

このページでは、ヘッドレス ウェブ SDK で使用できる API メソッドの一覧を示します。

会社とメニュー

会社の値とメニューを処理するメソッド。

メソッド

ヘッドレス SDK には、クライアント インスタンスで呼び出すことができるさまざまなメソッドが用意されています。

次に例を示します。

会社とメニュー

メソッド名	説明
getCompany	設定された会社情報を取得します。
getMenus	指定されたテナントで使用可能なすべてのメニューを一覧表示します。
getWaitTimes	メニューでさまざまなチャネルの現在の待ち時間を取得します。

getCompany

認証済みインスタンスに設定されている会社情報（会社名、サポートされている言語、機能設定など）を取得します。このメソッドは、内部インスタンス ID（OPTIONS.tenant）を副次的に設定します。そのため、通常は Client の作成後に最初に行われる呼び出しです。

メソッド シグネチャ

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: '[phone]' })
} 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[]>

警告: 以前のシグネチャ getTimeSlots(menuId, lang?) は非推奨になりました。前述の新しいオプションベースの署名に移行します。古いシグネチャは引き続き機能しますが、今後のリリースで削除される可能性があります。

戻り値

文字列（時間枠）の配列を返します。

インターフェース

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 は、予定された音声通話（コールバック）の予約にのみ適用されます。チャット、メール、インスタント コール チャネルに関する情報は返されません。提供されるメニューは、スケジュール設定された音声通話をサポートするように構成する必要があります。営業時間が定義され、そのメニューに少なくとも 1 つのエージェントがキューに登録されている必要があります。

一般的なユースケース:

• 空き時間がある場合にのみ、「コールバックをスケジュールする」という行動を促すフレーズを条件付きで表示する。

• スロットが利用できない場合に、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 メソッドについて説明します。チェックインの概要、有効化と構成の方法（待機時間、タイムアウト、キューの位置、再参加の動作）、レポートについては、Chat のチェックインをご覧ください。

名前	説明
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 を表示した直後に、このメソッドを 1 回呼び出します。サーバーは、チェックイン提示率の運用分析にこれを使用します。この呼び出しは内部で待機され、拒否される可能性のある 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 が利用可能になるか、チャットがキャンセルまたは終了するまでサーバーをポーリングします。プロバイダ チャネルが利用可能になると、このメソッドはリアルタイム プロバイダへの接続を開始します。Promise が解決されたときに接続がまだ完了していない可能性があります。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 とコブラウズのノンスをローカル ストレージから消去します。エラー時にもこの処理が行われるため、呼び出し元は読み込みに失敗した後にストレージのクリーンアップを手動で処理する必要はありません。

メソッド シグネチャ

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

戻り値

Chat インスタンスを返します。

警告: エラーが発生した場合、このメソッドは、保存されているチャットとコブローズ セッション ID をローカル ストレージから消去してから再スローします。保存されているセッション参照は、呼び出しが失敗すると無効になります。

使用例

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

loadOngoingChat

現在進行中のチャット セッションがある場合は、その読み込みを試みます。進行中のチャットが見つからない場合は null を返します。

メソッド シグネチャ

loadOngoingChat(): Promise<Chat | null>

戻り値

見つかった場合は Chat インスタンスを返し、進行中のチャットがない場合は null を返します。チャットが進行中でない場合は、ストレージ値を消去します。

警告: エラーが発生した場合、このメソッドは再スローする前に、保存されているチャット ID をローカル ストレージから消去します。呼び出しが失敗すると、保存されているセッション参照は無効になります。

使用例

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 の配列を返します。失敗した場合は空の配列を返します。

警告: このメソッドは、失敗してもスローしません。メッセージの取得に失敗した場合は、空の配列（[]）を返します。try/catch に依存せず、代わりに戻り値を確認してください。

インターフェース

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

現在のチャット セッションでテキスト メッセージを送信します。

このメソッドは、送信前に未加工のコンテンツをサニタイズし、結果が空の場合は早期に（no-op）戻ります。チャットがタスク仮想エージェント フロー（inTask）にある場合、メッセージは通常のチャネルではなく、タスク仮想エージェント Agent Endpoint を介してルーティングされます。サーバーサイドの削除が有効になっている場合、メッセージはリアルタイム プロバイダを直接経由するのではなく、サーバー エンドポイントを使用して送信されます。

メソッド シグネチャ

sendTextMessage(rawContent: string): Promise<void>

使用例

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

sendFileMessage

3 段階のプロセスで、現在のチャット セッションにファイルをアップロードします。まず、サーバーから事前署名付きの Cloud Storage URL を取得し、その URL にファイルを直接アップロードします。その後、アップロードが完了したことをサーバーに確認します。アップロード ルートは、ファイルの 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

現在のチャット セッションのチャット偏向構成を取得します。これには、偏向が有効かどうか、待機時間のしきい値、使用可能な偏向オプションが含まれます。

チャットでデフレクションが有効になっていない場合（サーバー レスポンスの enabled フィールドが false の場合）、null を返します。呼び出し元は、レスポンスを読み取る前に 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([
   "[e-mail]",
   "[e-mail]",
 ])
} 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>

警告: チャットのフィードバック タイプが 'survey' でない場合、このメソッドはすぐにスローされます。呼び出し元は、呼び出しの前に chat.feedbackType === 'survey' を確認するか、エラーを処理する必要があります。

インターフェース

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>

警告: チャットのフィードバック タイプが 'rate' でない場合、このメソッドはすぐにスローされます。呼び出し元は、呼び出しの前に chat.feedbackType === 'rate' を確認するか、エラーを処理する必要があります。

インターフェース

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: "[e-mail]",
   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

エージェントと共有してセッションを開始できる一意の共同閲覧（画面共有）セッション コードを生成します。まだ初期化されていない場合は、画面共有クライアントを初期化します。呼び出しごとに新しいノンスを生成するのではなく、ストレージから既存のノンスを再利用します。これにより、ページ読み込みをまたいで同じセッション コードを取得できます。

メソッド シグネチャ

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

戻り値

画面共有コードの文字列を返します。失敗した場合は空の文字列（''）を返します。

警告: このメソッドは、失敗してもスローしません。try/catch に依存せず、代わりに戻り値を確認してください。

使用例

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

startCobrowse

アクティブなチャット中に、エンドユーザー側から共同ブラウジング（画面共有）セッションの開始をリクエストします。

メソッド シグネチャ

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

警告: 現在のチャットが cobrowsable: true で作成されていない場合、このメソッドはスローされます。呼び出し元は、呼び出し前に chat.cobrowsable を確認することで、スローを回避できます。

使用例

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

restoreCobrowseSession

ブラウザ ウィンドウが再度開かれた後、またはウィジェットが再読み込みされた後に、以前にアクティブだった共同ブラウジング セッションの復元を試みます。

メソッド シグネチャ

restoreCobrowseSession(): Promise<void>

戻り値

Promise<void> を返します。このメソッドは、クライアント オプションで共同ブラウジングが有効になっていない場合や、以前の共同ブラウジング セッションがストレージに存在しない場合は、no-op（エラーなしですぐに返される）になります。

警告: このメソッドはスローしません。復元中にエラーが発生した場合、このメソッドはエラーを内部的にログに記録し、保存されている画面共有セッションをクリアしてから、正常に復帰します。呼び出し元は try/catch を必要としません。

使用例

// 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-op としてすぐに戻ります。これらの遷移は内部で処理されます。

• 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)
}

関連インターフェース

interface ChatResponse {
 //...
 post_session_required?: boolean;
 post_session_opt_in_required?: boolean;
 post_session_transfer_status?: string;
}

• post_session_required - チャット後にセッション後の対応が必要。

• post_session_opt_in_required - オプトインが有効になっているかどうか。

• post_session_transfer_status - PostSessionStatus 列挙型の 1 つ。

デバッグ

名前	説明
getLogs	SDK から内部デバッグログを取得します。
printLogs	内部デバッグログをブラウザ コンソールに出力します。

getLogs

SDK によって収集された内部デバッグログ（ブリッジレベルとルートレベルの両方のログを含む）を取得します。統合に関する問題のトラブルシューティングに役立ちます。

メソッド シグネチャ

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

戻り値

LogHistoryData の 2 つの配列を含むオブジェクトを返します。

インターフェース

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

注: ブリッジログは、フェッチ自体がルートログ エントリを生成するため、最初に内部でフェッチされます。その結果、rootLogs は意図的にその最終ログをキャプチャします。

粒度

各 LogHistoryData エントリは、1 つのログイベントをキャプチャします。

• 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 ステータス以外のサーバーサイドのリクエスト トレースまたはバックエンドの詳細。

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
}