> For the complete documentation index, see [llms.txt](https://docs.ok-sky.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ok-sky.com/js-sdk/widget.md).
# widget
### 概要
チャットウィジェットを表示するためのJavascript APIです。
* JS SDKのoptions部分にログイン情報やユーザ情報を追加できます。
* ユーザ情報は接客管理サイトの「来訪者詳細」に表示されます。
* ユーザ情報のキーワードは接客管理サイトの「マスターキーワード」に自動登録されます。
### 対象
* 来訪者用のチャットウィジェットを導入するウェブサイトがある
* HTML / JavaScriptに関する基本的な知識がある
## JS SDKの導入
1. JS SDKの読み込み
2. チャットウィジェットの表示
### JS SDKの読み込み方法
```markup
```
* `` 内に記載
### チャットウィジェットの表示方法
```javascript
```
* `` 直後に記載
* ① ウィジェットID
* ウィジェットIDは、接客管理サイトにて、「ウィジェット」管理ページにて、取得することができます。
* ② OK SKYシステムのURL
* 接客管理サイトのURLから取得することができます。
* `https://から始まり、/で終わる` 形で、 `https://{OK SKYシステムのFQDN}/` の形になります。
### GA(Google Analytics)でトラッキングする
```javascript
```
* オプションとして、 `ga_client_code` をキーとして、トラッキングコードを設定します。
## ログイン情報 / ユーザ情報の追加方法
ログイン方法やユーザ情報は `OkskyChat()` 関数の第三引数に追加します。 上の導入手順のコードに当てはめた場合、以下のようになります。
```javascript
```
### ログイン情報
* `login: {}` 内に `key: value` の形で追加します。
* `key` 及び `value` は任意の値を設定できるため、チャットウィジェットを導入するウェブサービス内の顧客情報も使用可能です。
* 例1) `user_id: 123`
* 例2) `account_code: "ABCDE12345"`
* ログイン情報は顧客を識別するための情報なので、ユーザ毎に一意になるよう設定してください。
### ユーザ情報
* `user_infos: {}` 内に `key: value` の形で追加します。
* `key` 及び `value` は任意の値を設定できるため、チャットウィジェットを導入するウェブサービス内の顧客情報も使用可能です。
## チャットウィジェットを開く・閉じる
| API | 概要 |
| ---------------------------------------- | -------------------------- |
| chatWidget.widget.open(room\_id(String)) | 特定のルームを指定してチャットウィジェットを表示する |
| chatWidget.widget.close | チャットウィジェットを非表示にする |
## コールバックを受け取る
| コールバックAPI | 概要 |
| -------------------------------------- | ----------------------------------------------- |
| chatWidget.widget.onReady | ウィジェットが利用できるようになった時のコールバック |
| chatWidget.event.onReceivedMessage | 現在開いているサポートでメッセージを受信した時のコールバック |
| chatWidget.event.onReceivedSomeMessage | 現在開いているサポートを含む、すべてのサポートのいずれかでメッセージを受信した時のコールバック |
例)
```javascript
```
## ビルトイン関数
### 他のイベント（クリック等）をトリガーにしてメッセージを送る
**chatWidget.postMessage(roomName, message, callback);**
```javascript
```
得られる結果（room）のサンプル
```javascript
{
awaiting_support: true,
client_id: 1,
create_user_id: 1,
created_at: "2020-01-01T10:10:10.111+09:00",
description: null,
enabled: null,
external_service_id: null,
helped_room_id: null,
id: 1,
is_private: false,
kind: "support_room",
latest_message_id: 1,
name: "sample-room-name-nEdOtD4RsN4",
room_code: null,
settings: {
message_classify: true,
message_dialog: false
},
updated_at: "2020-01-01T10:10:10.111+09:00"
}
```
* ① roomName: string
* サポートルーム名 `room.name` を指定します。指定しない場合、新規サポートルームにメッセージが送信されます。
* ② message: string
* 送信するメッセージを指定します。
* ③ callback: function
* メッセージの送信に成功した場合に、実行する処理を記述できます。メッセージを送信したサポートルーム `room` の内容を参照することができます。
### 現在のサポートルーム一覧を取得する
**chatWidget.rooms(callback);**
```javascript
```
得られる結果（response.data）のサンプル
```javascript
[
{ id: 1, name: "sample-room-name-1nEdOtDARsN" },
{ id: 2, name: "sample-room-name-2nEdOtDARsN" },
{ id: 3, name: "sample-room-name-3nEdOtDARsN" }
]
```
* ① callback: function
* サポートルーム一覧の取得に成功した場合に、実行する処理を記述できます。
### サポートルームと未読メッセージ件数の一覧を取得する
**chatWidget.unreadMessageCount(roomId, callback);**
```javascript
```
得られる結果（entry）のサンプル
```javascript
{
room_id: 1,
unread_message_counts: 2
}
```
* ① roomId: number
* `chatWidget.rooms` で取得したサポートルームの ID `room.id` を指定します。
* ② callback: function
* サポートルームと未読メッセージ件数の取得に成功した場合に、実行する処理を記述できます。
## ビルトイン関数サンプル
### いずれかのサポートルームでメッセージを受信した場合、サポートルームごとの未読件数を取得する
```javascript
window.onload = function() {
var chatWidget = new OkskyChat("fuku-6123606CD9858E57", "http://fuku.ok-sky.net/", {'ga_client_code':'GTM-XXXX'});
chatWidget.show();
chatWidget.event.onReceivedSomeMessage = function(event) {
handleReceivedSomeMessage(event);
};
function handleReceivedSomeMessage(event) {
chatWidget.rooms(function(response){
if (response.data.length != 0) {
response.data.forEach(function(room) {
chatWidget.unreadMessageCount(room.id, function(entry){
// サポートルームの ID と未読件数を取得
console.log("room_id:", entry.room_id);
console.log("unread_message_counts:", entry.unread_message_counts);
});
});
}
});
};
});
```