Helpshift API

ウィジェットを開く

会話ウィンドウを任意のタイミングで開く場合（ユーザーによるランチャーボタンの明示的なクリックを除く）、以下の API を呼び出すことで実現可能です。これは、先回りしたヘルプをトリガーする場合に便利です。

Helpshift("open");

ウィジェットを閉じる

同様に、会話ウィンドウを任意のタイミングで閉じるには、以下の API を呼び出すことで実現可能です。

Helpshift("close");

ウィジェットを非表示にする

以下の API を呼び出すことで、Web チャット（ランチャーとウィジェットの両方）を完全に非表示にすることができます。

Helpshift("hide");

注意

特定のページで、または特定のユーザーに対してウィジェットを非表示にする場合には、この API を使用すると良いかもしれません。

ウィジェットを表示する

以下の API を呼び出すことで、Web チャット（ランチャーとウィジェットの両方）を（hide API 経由で）非表示にした後でもう一度表示することができます。

Helpshift("show");

注意

この API は、以前非表示にした Web チャットの可視性を復元します。たとえば、hide API を呼び出す前にウィジェットが開いていた場合、show API はウィジェットを開いた状態で表示します。この API は、可視性に関連する動作を保持します。

可視性の状態

Helpshift の設定を更新する

Web ページの読み込みが完了した後にhelpshiftConfigオブジェクトを更新する場合、以下の API を呼び出すことで実現可能です。

Helpshift("updateHelpshiftConfig");

注意

この API は、シングルページの Web アプリケーションに最適です。

例: シングルページのアプリケーションでログイン後にユーザー関連データを取得する場合、更新されたユーザーデータを Web チャットに渡すには、ユーザーデータを使用してグローバルな helpshiftConfig オブジェクトを更新し、上記の API を呼び出します。

// Initial helpshift config object during page load
helpshiftConfig = {
    platformId: "<YOUR_PLATFORM_ID>",
    domain: "<YOUR_DOMAIN>",
    .
    .
};
.
.
.
// After user login, you can update the user data in config object.
helpshiftConfig.userId = "<LOGGED_IN_USER_ID>";
Helpshift("updateHelpshiftConfig");

重要

更新を試みる場合には、helpshiftConfigオブジェクトを上書きしないようにご注意ください。

注意

1. この API は、ユーザー関連データ、言語、フルプライバシー、widgetOptions など、すべてのhelpshiftConfigオブジェクトオプションに適用されます。
2. 会話が開始されると、この API を呼び出してもユーザー ID が更新されたり進行中の会話のカスタム問題フィールドが更新されたりすることはありません。
3. この API を呼び出すと、ウィジェットが再読み込みされます。ユーザーがウィジェットを開いている状態でこの API が呼び出された場合、ユーザーに対して読み込み中インジケーターが表示され、更新されたユーザーの会話が表示されます。

最初のユーザーメッセージを設定する

初期ユーザーメッセージをエンドユーザーに入力させるのではなく API を介して設定する場合、以下の API を使用することで実現可能です。

var userMessage = "Hello, how can I track my order?";
Helpshift("setInitialUserMessage", userMessage);

注意

会話が開始される前にこの API を呼び出す必要があります。つまり、会話が開かれていないとき、つまり新規のユーザーがウィジェットを開いたとき、または既存のユーザーが会話を閉じたときにのみ動作します。既存の会話の最中にこの API を呼び出しても、効果はありません。

イベント

Helpshift ウィジェットは、さまざまなシナリオにおいて以下のようなイベントを発生させます。イベントを管理するには、addEventListener API およびremoveEventListener API を使用します。

新しい未読メッセージイベント

このイベントは、ユーザーに新しい未読メッセージがあるときに発生します。このイベントをリッスンするには、埋め込みコードの後に以下のコードを追加します。

注意

このイベントは、未読メッセージの数が変更されたときにブラウザー通知を表示するために使用することもできます。

詳細については、「ブラウザー通知」を参照してください。

新しい未読メッセージイベントハンドラーの追加

var newUnreadMessagesEventHandler = function (data) {
  console.log("Unread count = ", data.unreadCount);
};
Helpshift(
  "addEventListener",
  "newUnreadMessages",
  newUnreadMessagesEventHandler
);

新しい未読メッセージイベントハンドラーの削除

Helpshift(
  "removeEventListener",
  "newUnreadMessages",
  newUnreadMessagesEventHandler
);

ユーザーの変更イベント

このイベントは、ユーザが電子メールリンクをクリックして Web チャットをもう一度開いたときに、ユーザーの識別子が元のユーザーが会話を開始したときからこのユーザーが電子メールのリンクをクリックした時へと 変更されたことを検出した場合に発生します。

注意

このイベントを使用するには、Web チャットの「メールでフォローアップ」トグルを有効にする必要があります。ユーザーの変更イベントは、 以下のようなシナリオにおいて、リンクのクリック後にユーザーの識別子が変更された場合に最適なユーザーエクスペリエンスを構築するために 使用することができます。

1. ユーザーが匿名でチャットを開始し（チャットの最中はログインしていない）、リンクをクリックする前にログインした場合。
2. ユーザーがログインユーザーとしてチャットを開始したが、リンクをクリックする前にログアウトした場合。
3. ユーザーがログインユーザーとしてチャットを開始したが、リンクをクリックする前に別のユーザーとしてログインした場合。

ユーザーの変更イベントハンドラーの追加

var userChangedHandler = function (data) {
  console.log("User's original state is: " + data.originalState);
  console.log("User was having conversation on: " + data.pageUrl);
};
Helpshift("addEventListener", "userChanged", userChangedHandler);

ユーザーの変更イベントハンドラーの削除

Helpshift("removeEventListener", "userChanged", userChangedHandler);

イベントによって返された値の使用

名前	値	使用方法
originalState（これはチャットを開始したときのユーザーの状態を示しています）	logged-in	ユーザーが元々ログインしていた場合、もう一度ログインするように促す必要があります。ユーザーのログイン認証情報がチャットを開始したときの認証情報と同一である限り、ユーザーは会話を再開することができます。
	anonymous	ユーザーが元々匿名（ログインしていない状態）だった場合には、プロンプト表示によってログアウトを促すか、自動的にログアウトさせることによって会話を再開できるようにする必要があります。
pageUrl	ユーザーがチャットを開始したページ	弊社では、（元々の状態に基づいて）ログアウトまたはログインに成功した後にユーザーをチャットを開始したページへと移動することを強く推奨しています。そうすることにより、ユーザーが正しい文脈が維持されたページに戻ることができます。

注意

また、Open Widget APIを使用し、 ログインまたはログアウト（元の状態によって異なります）が成功した後にユーザーのために自動でウィジェットを開くことをお勧めしています。

ウィジェットの切り替えイベント

このイベントは、ユーザーが Web チャットのメインウィンドウを最小化または最大化したときにトリガーされます。イベントデータオブジェクトは、メインのチャットウィンドウの可視性を示すブーリアン値のプロパティ"visible"を保持しています。参考までに、以下の例をご覧ください。

ウィジェットの切り替えイベントハンドラーの追加

var widgetToggleEventHandler = function (data) {
  console.log("Visibility = ", data.visible);
};
Helpshift("addEventListener", "widgetToggle", widgetToggleEventHandler);

ウィジェットの切り替えイベントハンドラーの削除

Helpshift("removeEventListener", "widgetToggle", widgetToggleEventHandler);

会話の開始イベント

このイベントは、ユーザーが会話の中で最初のメッセージを送信したときにトリガーされます。イベントのデータオブジェクトにはmessageプロパティが含まれており、これにはエンドユーザーが会話を始めるために送信したメッセージの文字列が含まれています。ご参考までに、以下の例をご確認ください。

会話の開始イベントハンドラーの追加

var conversationStartEventHandler = function (data) {
  console.log("Message = ", data.message);
};
Helpshift(
  "addEventListener",
  "conversationStart",
  conversationStartEventHandler
);

会話の開始イベントハンドラーの削除

Helpshift(
  "removeEventListener",
  "conversationStart",
  conversationStartEventHandler
);

メッセージの追加イベント

このイベントは、ユーザーが会話内でメッセージを追加したときにトリガーされます。追加されるメッセージには、テキストメッセージ、ボットの入力を介した応答、添付ファイルなどが想定されています。イベントのデータオブジェクトにはtypeプロパティとbodyプロパティが含まれており、これらはユーザーが追加したメッセージの種類と本文を示しています。ご参考までに、以下の例をご確認ください。

メッセージの追加イベントハンドラーの追加

var messageAddEventHandler = function (data) {
  if (data.type === "attachment") {
    console.log("user sent an attachment");
  }
  console.log("Message = ", data.body);
};
Helpshift("addEventListener", "messageAdd", messageAddEventHandler);

メッセージの追加イベントハンドラーの削除

Helpshift("removeEventListener", "messageAdd", messageAddEventHandler);

CSAT の送信イベント

このイベントは、会話の終了後にユーザーが CSAT（顧客満足度）評価を送信したときにトリガーされます。イベントのデータオブジェクトにはratingプロパティとadditionalFeedbackプロパティが含まれており、これらはユーザーが CSAT フォームを介して提供した（星による）評価と追加のコメントを示しています。ご参考までに、以下の例をご確認ください。

CSAT の送信イベントハンドラーの追加

var csatSubmitEventHandler = function (data) {
  console.log("Rating = ", data.rating);
  console.log("Additional Feedback = ", data.additionalFeedback);
};
Helpshift("addEventListener", "csatSubmit", csatSubmitEventHandler);

CSAT の送信イベントハンドラーの削除

Helpshift("removeEventListener", "csatSubmit", csatSubmitEventHandler);

会話の終了イベント

このイベントは会話が終了（解決または拒否）し、再開できない場合にトリガーされます。

会話の終了イベントハンドラーの追加

var conversationEndEventHandler = function () {
  console.log("Conversation has ended.");
};
Helpshift("addEventListener", "conversationEnd", conversationEndEventHandler);

会話の終了イベントハンドラーの削除

Helpshift(
  "removeEventListener",
  "conversationEnd",
  conversationEndEventHandler
);

注意

これは、「閉じる」ボタンがクリックされたときにのみトリガーされるchatEndイベントとは異なり、setEndUserFirstMessage API と共に使用されます。

conversationEndイベントは、conversationResolvedイベントおよびconversationRejectedイベント（以下で説明）と共にトリガーされます。このイベントは、会話が解決または拒否され、解決後のワークフロー（例: 解決に関する質問）が終了したことを示しています。たとえば、"解決に関する質問"機能をオンにしている場合、典型的なイベントの流れは、「conversationResolved→ ユーザーが解決に関する質問に回答する →conversationEnd」のようになります。

会話の拒否イベント

このイベントは、エージェントが会話を拒否したときにトリガーされます。

会話の拒否イベントハンドラーの追加

var conversationRejectedEventHandler = function () {
  console.log("Conversation has been rejected by the agent.");
};
Helpshift(
  "addEventListener",
  "conversationRejected",
  conversationRejectedEventHandler
);

会話の拒否イベントハンドラーの削除

Helpshift(
  "removeEventListener",
  "conversationRejected",
  conversationRejectedEventHandler
);

会話の解決イベント

このイベントは、エージェントが会話を解決したときにトリガーされます。

会話の解決イベントハンドラーの追加

var conversationResolvedEventHandler = function () {
  console.log("Conversation has been resolved by the agent.");
};
Helpshift(
  "addEventListener",
  "conversationResolved",
  conversationResolvedEventHandler
);

会話の解決イベントハンドラーの削除

Helpshift(
  "removeEventListener",
  "conversationResolved",
  conversationResolvedEventHandler
);

会話の再開イベント

解決に関する質問が有効化されている場合、ユーザーに対して解決の内容に満足しているかどうかが質問されます。ユーザーがそれを拒否し、新しいメッセージを送信すると会話が再開され、会話の再開イベントがトリガーされます。

会話の再開イベントハンドラーの追加

var conversationReopenedEventHandler = function () {
  console.log("Conversation has been reopened by the user.");
};
Helpshift(
  "addEventListener",
  "conversationReopened",
  conversationReopenedEventHandler
);

会話の再開イベントハンドラーの削除

Helpshift(
  "removeEventListener",
  "conversationReopened",
  conversationReopenedEventHandler
);

エージェントメッセージの受信イベント

このイベントは、エージェントのメッセージがエンドユーザーに「読まれる」たびにトリガーされます。このイベントはボットのメッセージに対してはトリガーされません。

エージェントメッセージの受信イベントハンドラーの追加

var agentMessageReceivedEventHandler = function (message) {
  console.log(message);
};

Helpshift(
  "addEventListener",
  "agentMessageReceived",
  agentMessageReceivedEventHandler
);

受信するデータは、以下の形式になります。

type AgentMessage = {
  // The actual message sent by the agent
  body: string;
  // Conversation ID of the ongoing issue
  publishId: string;
  // Unix epoch timestamp in ms
  createdTs: number;
  // Attachments, if they are present
  attachments?: Array<{
    url: string;
    // Size of the attachment in bytes
    size: number;
    // The MIME type
    contentType?: string;
    fileName?: string;
  }>;
};

注意

• 添付ファイルのキーは、エージェントが添付ファイルを送信した場合にのみ存在します。
• エージェントが送信した添付ファイルには必要な MIME タイプや名前がない可能性があるため、 それらの値がペイロードから欠落する可能性があります。

エージェントメッセージの受信イベントハンドラーの削除

Helpshift(
  "removeEventListener",
  "agentMessageReceived",
  agentMessageReceivedEventHandler
);

ユーザーによるアクションをクリック時のイベント

エンドユーザーがアクションカードのリンクをクリックすると、このイベントがトリガーされます。

ユーザーによるアクションのクリックイベントハンドラーの追加

var userClickOnActionEventHandler = function (data) {
  console.log("User clicked on action");
  console.log(data);
};

Helpshift(
  "addEventListener",
  "userClickOnAction",
  userClickOnActionEventHandler
);

受信するデータは、以下の形式になります。

type ActionCardInfo = {
  actionType: "link" | "call";
  // This will be a URL or a phone number
  actionData: string;
};

ユーザーによるアクションのクリックイベントハンドラーの削除

Helpshift(
  "removeEventListener",
  "userClickOnAction",
  userClickOnActionEventHandler
);