ビジネスメッセンジャーのウィジェットでのJavaScript APIの利用

こちらのヘルプ記事では、JavaScript APIを利用してビジネスメッセンジャーのウィジェットをカスタマイズする方法について説明します。インスタントメッセージの経路の設定、ZOHOIMのグローバルオブジェクトの作成、ウィジェットのレイアウトと外観のカスタマイズについて紹介します。

JavaScript APIの概要

ビジネスメッセンジャーでは、JavaScript APIを利用できます。JavaScript APIを利用すると、データを事前に入力したり、連絡先の詳細を取得したりできます。また、ウィジェットの外観をカスタマイズすることも可能です。

JavaScript APIの利用

JavaScript APIを利用するには、ビジネスメッセンジャーの埋め込みコードをコピーして、自社のWebサイトのHTMLコード内に貼り付ける必要があります。コードを貼り付ける前に、コード内でJavaScript APIの各情報が適切に設定されていることをご確認ください。

ビジネスメッセンジャーのウィジェットの設定

ビジネスメッセンジャーのウィジェットを設定するには：

インスタントメッセージの設定画面で、ビジネスメッセンジャーの経路を作成します。
経路の埋め込み用のコードをコピーします。
埋め込み用のコードをビジネスメッセンジャーの設置先のWebページに挿入します。
コードを挿入する前にZOHOIMオブジェクトを初期化します。

window.ZOHOIM = window.ZOHOIM || {};

ビジネスメッセンジャーのウィジェットのレンダリングに必要な情報をwindow.ZOHOIM変数内に設定します。

ビジネスメッセンジャーの埋め込み用コードのサンプル

JavaScript

<script type="text/javascript" nonce="{place_your_nonce_value_here}"
  src="https://im.zoho.com/api/v1/public/channel/435798000000140015/widget" defer>
  var _d=document;_d.prefilledMessage=
</script>

APIの設定

window.ZOHOIMで以下の情報を設定します。

属性名	型	説明
widgetContainerId	文字列	ビジネスメッセンジャーがレンダリングされる要素のIDです。
widgetLayout	オブジェクト	ビジネスメッセンジャーのウィジェットのレイアウトのカスタマイズに必要な設定について記述します。
widgetLayout.showWidget	真偽値	ビジネスメッセンジャーのウィジェットを表示するかどうかを設定します。
widgetLayout.needWidgetBubble	真偽値	ビジネスメッセンジャーのウィジェットを吹き出しアイコンとして表示するかどうかを設定します。
widgetLayout.needCloseIcon	真偽値	ビジネスメッセンジャーのウィジェットの上部に終了アイコンを表示するかどうかを設定します。
widgetProps.sessionVariableValues	配列	自動ガイドボットのセッション変数を設定します。詳細はこちら
**customStyles	文字列	ビジネスメッセンジャーのウィジェットのスタイルをカスタマイズするために必要な設定について記述します。
customStyles.mode	文字列	ビジネスメッセンジャーのテーマを設定します。例："light"（ライト）、"dark"（ダーク）。
customStyles.theme	文字列	ビジネスメッセンジャーのウィジェットのテーマについて記述します。例：16進数カラーコード
customStyles.actionTheme	文字列	ビジネスメッセンジャーのウィジェットのアクションテーマについて記述します。例：16進数カラーコード
customStyles.wallpaper	オブジェクト	ビジネスメッセンジャーのウィジェットの壁紙の設定について記述します。
customStyles.wallpaper.src	オブジェクト	モード別のビジネスメッセンジャーのウィジェットの壁紙の設定について記述します。
customStyles.wallpaper.src.light	文字列	ライトモードの壁紙を設定します（画像URL）。
customStyles.wallpaper.src.dark	文字列	ダークモードの壁紙を設定します（画像URL）。
poweredByTag	オブジェクト	ビジネスメッセンジャーのウィジェットのフッターにおける「powered by」タグの表示設定について記述します。
poweredByTag.isChecked	真偽値	ビジネスメッセンジャーのフッターに「powered by」タグを表示するかどうかを設定します。
customHandlers	オブジェクト	ビジネスメッセンジャーのウィジェットの機能に必要な設定について記述します。
customHandlers.closeButtonHandler	関数	完了アイコンがクリックされたときに実行する処理を設定します。
customHandlers.backButtonHandler	関数	戻るアイコンがクリックされたときに実行する処理を設定します。
customHandlers.openArticle	関数	記事のリンクがクリックされたときに実行する処理を設定します。詳細はこちら

APIの実行

以下のメソッドを利用すると、ビジネスメッセンジャーのウィジェットとWebアプリ間でデータをやりとりできます。

メソッド名	説明	引数	戻り値
triggerEvent	特定のイベントを実行し、実行されたイベントを購読しているすべてのメソッドを実行します。	ZOHOIM.triggerEvent('eventName',...args)	NIL
subscribeToEvent	メソッドが特定のイベントを購読するように設定します。	ZOHOIM.subscribeToEvent( 'eventName', method)	NIL

以下は、ビジネスメッセンジャーのウィジェットのレンダリング方法について示したサンプルコードです。

JavaScript

<html>
<head>
<title>Page Title</title>
<script>
window.ZOHOIM = window.ZOHOIM || {};
window.ZOHOIM.widgetContainerId = "test";
window.ZOHOIM.widgetLayout = { needWidgetWithBubble : false, needCloseIcon : true};
window.ZOHOIM.customStyles = '{ "mode": "light", "theme": "#71198c","actionTheme":"#1a7063", "wallpaper": {"src": {"light":"https://fastly.picsum.photos/id/703/536/354.jpg?hmac=1NZ7SzrTrnA-1O2S18kJC-IFIOZyYeHt8x98Iqdd5kM"}},"poweredByTag": { "isChecked": false } }';
customCloseButtonHandler = ()=>{alert('clicked the close button');}
customBackButtonHandler = ()=>{
  if(a===1){
    a=0;
    window.ZOHOIM.triggerEvent('showCloseIcon',true);
  }else{
    a=1;
    window.ZOHOIM.triggerEvent('showCloseIcon',false);
  }
}
window.ZOHOIM.customHandlers = {
 closeButtonHandler : customCloseButtonHandler,
 backButtonHandler : customBackButtonHandler
}
</script>

<script type="text/javascript" nonce="{place_your_nonce_value_here}" src="https://implus.localzoho.com/api/v1/public/channel/c572beb392335194a3f8e528fb092408/widget" defer> var _d=document;_d.prefilledMessage= </script>
</head>

<body>
<div id="test" style="height: 500px; width: 400px; border: 1px solid black;"></div>
</body>
</html>

対応言語と代替表示

widgetProps.languagesを使用して、ビジネスメッセンジャーのウィジェットに表示する言語を設定できます。

JavaScript

<script type='text/javascript'>window.ZOHOIM=window.ZOHOIM||function(a,b){ZOHOIM[a]=b;};window.ZOHOIM.prefilledMessage="";</script>
<script>
window.ZOHOIM = window.ZOHOIM || {};
window.ZOHOIM.locale = 'en_US'; // localeは必須です
window.ZOHOIM.widgetProps = { languages: ['en_US','fr_FR','ta_IN','ar_EG']}; // localeはlanguagesの一覧に含める必要があります
</script>

使用する言語に応じて、['en_US','fr_FR','ta_IN','ar_EG']内の言語コードを同じ形式で置き換えます。

widgetProps.languagesに設定した言語は、言語の選択リストに表示されます。ただし、ここに言語を追加しても、ビジネスメッセンジャーのウィジェットがその言語に対応しているとは限りません。

言語の選択リストで選択する言語、ビジネスメッセンジャーのウィジェットUIの表示言語、自動ガイドボットの応答言語は、それぞれ異なる言語設定に基づいて決まります。

言語の選択リスト：widgetProps.languagesに設定されている言語が表示されます。

ビジネスメッセンジャーのウィジェットUI：選択した言語に対応するインスタントメッセージの翻訳が用意されているかどうかによって表示言語が決まります。

インスタントメッセージの対応言語

コード	言語	コード	言語
`en_US`	英語（米国）	`nb_NO`	ノルウェー語（ブークモール）
`ar_EG`	アラビア語（エジプト）	`nl_NL`	オランダ語
`da_DK`	デンマーク語	`or_IN`	オディア語
`de_DE`	ドイツ語	`pl_PL`	ポーランド語
`es_ES`	スペイン語	`pt_BR`	ポルトガル語（ブラジル）
`fr_FR`	フランス語	`ro_RO`	ルーマニア語
`hi_IN`	ヒンディー語	`ru_RU`	ロシア語
`in_ID`	インドネシア語	`sv_SE`	スウェーデン語
`is_IS`	アイスランド語	`ta_IN`	タミル語
`it_IT`	イタリア語	`te_IN`	テルグ語
`iw_IL`	ヘブライ語	`th_TH`	タイ語
`ja_JP`	日本語	`tr_TR`	トルコ語
`kk_KZ`	カザフ語	`vi_VN`	ベトナム語
`ko_KR`	韓国語	`zh_CN`	中国語（簡体字）
		`zh_TW`	中国語（繁体字）

自動ガイドボットの応答：自動ガイドボットの応答言語は、選択した言語にインスタントメッセージが対応しているかどうかによって決まります。

自動ガイドボットの対応言語の一覧については、自動ガイドボットの対応言語に関するドキュメントをご参照ください。

インスタントメッセージで対応していない言語を設定した場合

インスタントメッセージの翻訳が用意されていない言語でも、widgetProps.languagesに追加できます。その言語はビジネスメッセンジャーの言語の選択リストに表示され、選択できます。

ただし、その言語を選択すると、以下のように動作します。

選択した言語は、言語の選択リストでは現在の言語としてそのまま表示されます。
対応するインスタントメッセージの翻訳が用意されていないため、ビジネスメッセンジャーのウィジェットUIは、初期設定の言語である英語（en_US）で表示されます。
自動ガイドボットの応答言語は、選択した言語にインスタントメッセージが対応しているかどうかによって別途決まります。

重要：ビジネスメッセンジャーの言語の選択リストに言語が表示されていても、その言語がwidgetProps.languagesに設定されていることを示すだけです。インスタントメッセージや自動ガイドボットがその言語に対応していることを示すものではありません。

連絡先情報の取得用のAPI（Web）

widgetPropsを使用して連絡先情報を提供できます。

属性名	型	説明
ContactInfo	オブジェクト	連絡先の詳細を記述します。

サンプル

JavaScript

window.ZOHOIM.widgetProps = { 'contactInfo': {'name':'Manoj','phone': '+91203354', 'email': 'abc@gmail.com'}};

関連情報（iOS）：ビジネスメッセンジャー用SDK（iOS）の連絡先情報の設定

認証用API

以下では、ビジネスメッセンジャーで認証プロセスを処理するための設定を紹介します。

Csrfcookieを設定するためのメソッド：

JavaScript

window.ZOHOIM.setCsrfParamName(csrfParamName);
window.ZOHOIM.setCsrfToken(csrfToken);

OAuthを設定するためのメソッド（JWT認証の場合）：

JavaScript

window.ZOHOIM.setAuthtoken(token);

ドメインを設定するためのメソッド：

JavaScript

window.ZOHOIM.setCustomDomainUrl(DomainURL);

ビジネスメッセンジャーにZohoAccountIdを追加するためのメソッド：

JavaScript

window.ZOHOIM.setZaid(zaid);

レンダリング前の処理の設定：

ウィジェットをレンダリングする前に実行する処理を設定できます。

JavaScript

window.ZOHOIM.beforeRenderCallback= () => {
        //todo
}

ビジネスメッセンジャーのウィジェットの表示変更

ビジネスメッセンジャーの利用者がウィジェットの表示を管理できるようにするための公開メソッドが導入されました。メソッドを利用することにより、利用者がウィジェットを操作して、表示を管理できるようになります。

利用可能なイベント

イベント名	説明
openWidget	ビジネスメッセンジャーのウィジェットを開きます。
closeWidget	ビジネスメッセンジャーのウィジェットを閉じます。
toggleWidget	ウィジェットの開閉状態を切り替えます。
showBubble	ウィジェットの吹き出しアイコンを表示します。
hideBubble	ウィジェットの吹き出しアイコンを非表示にします。

サンプル

以下のコードは、ウィジェット管理用の新しいメソッドの利用例を示したサンプルです。

JavaScript

<script>
window.ZOHOIM = window.ZOHOIM || {};
function closeWidget() {
   const { triggerEvent } = window.ZOHOIM;
   triggerEvent('closeWidget');
}
function openWidget() {
   const { triggerEvent } = window.ZOHOIM;
   triggerEvent('openWidget');
}
function toggleWidget() {
   const { triggerEvent } = window.ZOHOIM;
   triggerEvent('toggleWidget');
}
</script>

<button type="button" onclick="openWidget()">Open</button>
<button type="button" onclick="closeWidget()">Close</button>
<button type="button" onclick="toggleWidget()">Toggle</button>