Live Chat の JavaScript SDK

Live Chat には、さまざまな方法でウィジェットを操作できる JavaScript SDK が用意されています。すべてのインタラクションは、ウィジェットが初期化された場所であればどこでも利用できるliveChatと呼ばれるグローバルに定義された関数を介して行われます。Typescript構文でのこの関数の定義は次のとおりです。

liveChat(command: string, arg?: any, callback?: (e?: any, r?: any) => any);

例を見てみましょう。次のスニペットは、ウィジェットを初期化します。

• liveChat(...); は、ウィジェットとの対話に使用されるグローバル関数です。

• 'init' は関数の最初のパラメータです。これはコマンドと呼ばれ、ウィジェットに何をしたいかを指示します。この場合、ウィジェットに自身を初期化するように指示します。コマンドの詳細と詳細については、コマンド セクションを参照してください。

• '85ea1938-f457-496d-8532-8fa489beea63' は関数の 2 番目のパラメーターです。これは コマンド引数 または arg と呼ばれ、コマンドの引数を提供します。コマンドには、引数、省略可能な引数、または必須の引数を指定できます。オプション性と引数の型は、どちらも特定のコマンドによって異なります。詳細については、コマンド セクションを参照してください。

• (error, result) => { ... }̇ は関数の 3 番目のパラメーターです。これはコールバック関数であり、コマンドの実行が終了すると呼び出されます。コールバックは 2 つのパラメーターの関数です - 最初のパラメーターはエラーを表し、2 番目のパラメーターは結果を表します。実行結果に応じて 1 つだけ定義されます。エラーパラメータは失敗した場合に常に定義され、結果パラメータは成功した場合に定義されます。

この関数は、NTT CPaaS アカウントで提供されているスニペットを使用して Live Chat が初期化されているコード内の任意の場所から呼び出すことができます。

コマンド

以下のセクションを読み、使用可能なコマンドの詳細を確認してください。

初期化

使用例

liveChat('init', '85ea1938-f457-496d-8532-8fa489beea63', myInitCallback);

細部

このコマンドは、他のコマンドの前に、最初のコマンドとして呼び出す必要があります。引数には、初期化するウィジェットの ID が必要です。ページをリロードせずに別のウィジェットIDで初期化する場合は、最初にClearまたはLog outコマンドを呼び出す必要があります。

認証

使用例

liveChat('auth', generateJwt(), myAuthCallback);

細部

このコマンドは、JWT で提供されるデータを使用して現在のユーザーを認証します。この方法で認証されたユーザーは、システム内で自動的に顧客として扱われます。つまり、認証を行うことで、ユーザーは自分の身元を確認し、以前の履歴にアクセスできます。

JWT の生成方法の詳細については、このページを確認してください。

ログアウトする

使用例

liveChat('logout', null, myLogoutCallback);

細部

このコマンドは、現在認証されているユーザーセッションをログアウトするために使用され、認証されたユーザーに対してのみ使用できます (最初に Auth コマンドを呼び出す必要があります)。実行すると、ウィジェットがリロードされ、デフォルト状態にリセットされます。

クリア

使用例

liveChat('clear', null, myClearCallback);

細部

このコマンドは意味的には Log out と同等ですが、唯一の違いは、Clear は認証されていないユーザーにも使用できることです。

見せる

使用例

liveChat('show', null, myShowCallback);

細部

このコマンドは単にウィジェット自体を開く(表示する)ので、ウィジェットがまだ展開されていない場合は展開されます。

隠れる

使用例

liveChat('hide', null, myHideCallback);

細部

このコマンドは単にウィジェット自体を隠す(閉じる)ので、ウィジェットがまだ折りたたまれていないと折りたたまれます。

ランチャーを表示

使用例

liveChat('show_launcher', null, myShowLauncherCallback);

細部

このコマンドは、ウィジェットランチャーを表示するだけで、ウィジェット自体は展開しません。

ランチャーを隠す

使用例

liveChat('hide_launcher', null, myHideLauncherCallback);

細部

このコマンドは単にウィジェットランチャーを非表示にするため、ウィジェットを展開するとウィジェットが折りたたまれ、ランチャーも消えます。

テーマを設定

使用例

liveChat('set_theme', 'dark');

細部

このコマンドは、テーマ名でテーマを適用する場合に便利です。テーマは、NTT CPaaS アカウントの [チャネル] → [Live Chat] でウィジェット用に構成する必要があることに注意してください。

送信

想定される引数の構造

送信するメッセージを定義するオブジェクト。サポートされているタイプは次のとおりです。

基本的なメッセージペイロード

1. type (必須) - 文字列値 'BASIC'
2. message (オプション) - 文字列;メッセージのテキスト内容。
3. attachment (オプション) - 文字列。添付ファイルのコンテンツ (通常は base64 でエンコードされたファイルまたは URL)。
4. fileName (オプション) - 文字列。送信される添付ファイルの名前。attachmentが定義されている場合は、fileNameも定義する必要があります。
5. threadId (オプション) - 文字列。メッセージの送信先の既存のスレッドの ID。指定しない場合、メッセージは現在のユーザー セッションのアクティブな (開いている) スレッドに送信されます。

下書きメッセージペイロード

1. type (必須) - 文字列値 'DRAFT'
2. message (必須) - 文字列。チャット入力欄に設定する下書きメッセージです。
3. threadId (オプション) - 文字列。メッセージの送信先の既存のスレッドの ID。指定しない場合、メッセージは現在のユーザー セッションの現在アクティブな (開いている) スレッドに送信されます。

カスタム・データ・メッセージ・ペイロード

1. type (必須) - 文字列値 'CUSTOM_DATA'
2. customData (必須) - 任意。会話に関連するカスタムデータを含む構造化オブジェクト。
3. agentMessage (オプション) - 文字列。カスタムデータのコンテキストを提供するエージェントに表示されるメッセージ。未定義のままにすると、メッセージは表示されません。
4. userMessage (オプション) - 文字列。カスタム データに関連するユーザーに表示されるメッセージ。未定義のままにすると、メッセージは表示されません。
5. threadId (オプション) - 文字列。メッセージの送信先の既存のスレッドの ID。指定しない場合、メッセージは現在のユーザー セッションの現在アクティブな (開いている) スレッドに送信されます。

使用例

liveChat('send', { type: 'BASIC', message: 'Hello! I need help with my order.' }, mySendCommandCallback);

liveChat('send', { type: 'DRAFT', message: 'Hi, I need help with my recent order number:' }, mySendCommandCallback);

liveChat('send', { type: 'CUSTOM_DATA', customData: {'orderId': 'ORD-6789', 'action': 'track_order' }, agentMessage: 'User requested tracking info for order ORD-6789.', userMessage: 'Track my order.' }, mySendCommandCallback);

細部

このコマンドを使用すると、特定のスレッドまたは現在のユーザー セッションのアクティブな (開いている) スレッドにメッセージを送信できます。ペイロードで指定されたタイプに応じて、以下を送信できます。

• 基本メッセージ - ユーザーとエージェントに表示されるプレーンテキストメッセージまたは添付ファイル。
• 下書きメッセージ - チャット入力フィールドに事前に入力されたメッセージで、ユーザーは送信前にメッセージを編集できます。
• カスタムデータメッセージ - エージェントやユーザーのオプションの可視性を備えた構造化データメッセージで、チャットインターフェイスを乱雑にすることなくバックエンドプロセスを容易にします。

動作とスレッドのターゲット設定

• threadId を省略すると、メッセージはユーザーのセッション内のアクティブな (開いている) スレッドに送信されます。
• threadId を指定すると、その特定のスレッドにメッセージが送られます。

コンテキストデータの送信

想定される引数の構造

引数は、次のフィールドを持つオブジェクトである必要があります。

1. metadata (必須)
   1. 送信するデータを表すキーと値のペアを持つオブジェクト
   2. 例: { 'seconds_since_last_cart_visit': 178 }
2. multiThreadStrategy (オプション)
   1. 'ACTIVE' または 'ALL' の文字列値 2. 'ACTIVE' を指定すると、メタデータは、現在開かれているアクティブなスレッドにのみ送信されます 3. 'ALL' を指定すると、現在アクティブな対話を持つすべてのスレッドにメタデータが送信されます
   2. マルチスレッドウィジェットにのみ使用
   3. デフォルト値は 'ACTIVE' です

引数が全体としてどのように見えるかを確認するには、次の「使用例」セクションを参照してください。

使用例

liveChat('send_contextual_data', { metadata: {'color': 'green', 'size': 'M' }, multiThreadStrategy: 'ALL' }, myContextualDataCallback);

細部

このコマンドを使用すると、コンテキスト データを既存の会話に送信できます。会話の開始前(通常はユーザーが最初のメッセージを送信する前)にこのコマンドを呼び出した場合、ウィジェットが会話の作成の確認を受信すると、コンテキストデータリクエストがキューに入れられて実行されます。

これにより、会話の作成からデータの受信までの間に若干の遅延が生じる可能性があります。会話の作成に関するコンテキスト データの受信が予想される場合は、この遅延を考慮してください。

任意のデータをキーと値のペアの形式で会話に渡すことができます。たとえば、ウェブサイトにLive Chat機能を備えた衣料品店を想像してみてください。サイトを閲覧している顧客は Live Chat を介してチャットを開始し、会話の開始時に顧客の買い物かごに関するすべての情報がエージェントに送信されます。エージェントのインターフェイスの会話 コンテクストカードには、すべての共有データが自動的に表示されるため、エージェントは迅速かつ効率的にデータを確認できます。

言語を設定する

使用例

liveChat('set_language', 'it-IT', mySetLanguageCallback);

細部

このコマンドは、ウィジェットのローカライゼーションを更新し、更新を適用するために再読み込みします。言語タグを指定しない場合、またはタグがサポートされていない場合、ウィジェットはデフォルトで en-US になります。

サポートされている言語

現在、次の言語をサポートしています。