Smart Chat 公式マニュアル Ver.1.0

1. Smart Chatとは

Smart Chatは、Webサイト内の複数ページで同じ会話を継続できる埋め込み型チャットです。各ページに <script src="/chat/chat.js" defer></script> を読み込むことで、同一端末では同じスレッドが表示されます。

ユーザーにやさしい

難しい会員登録を求めず、表示名を登録してすぐ相談できます。

管理しやすい

NEW、最終発言者、未返信時間、件数、通知状態などを一覧で把握できます。

設置しやすい

ページ側はJavaScriptを1行読み込むだけ。チャット本体は別ディレクトリに置けます。

育てやすい

PHP＋JSON中心の軽量構成で、小さく始めて段階的に機能を追加できます。

本書について：これまでのSmart Chat開発スレッドで確定した仕様を中心に整理しています。実際の最新版ファイルで名称が異なる場合は、現行コードを優先してください。

2. 設計思想

ページではなく、端末に会話を持たせる

商品ページ、案内ページ、管理画面など、ユーザーがサイト内を移動しても相談が途切れないよう、ページURLではなく端末キーを基準にスレッドを識別します。最終ページURLは、管理者が「どこを見て相談したか」を把握する補助情報として保存します。

ユーザー側は親しみやすく、管理側は情報量を優先

ユーザー画面はLINEに近い会話型UI。管理画面は装飾よりも、未返信・重要度・件数・制御状態を一目で確認できることを優先しています。

小規模運用に合うJSON構成

DBを使わず導入しやすいことが大きな利点です。一方で、同時アクセス増加やデータ量増大時には、ファイルロック・バックアップ・将来的なDB移行を考慮します。

3. 利用の流れ

ページを開く→chat.js読込→端末確認→ 表示名登録→投稿→管理者が返信

ページ右下のチャットランチャーを開きます。
初回のみ表示名を登録します。
見出しと詳細を入力して送信します。見出しだけでも送信できます。
送信後は画面を再読込し、最新メッセージを表示します。
管理者が返信すると、設定に応じてユーザーへメール通知されます。

4. ユーザー画面

機能	内容
表示名	最大50文字。端末とスレッドを紐づけるために使用します。
見出し	最大50文字。相談内容の要点を入力します。
詳細	最大300文字。状況、希望、補足などを入力します。
メール通知	メール登録・変更・削除に対応。管理者返信時のみ通知する運用です。
ファイル送信	管理側で許可されている場合だけ表示されます。複数選択と分割送信に対応します。
投稿停止	管理者が停止した場合、履歴は見えても新規投稿できません。
履歴非表示	管理設定により、過去メッセージをユーザー側から隠せます。
UI非表示	ランチャーを含むチャットUI自体を非表示にできます。

表示更新：送信後は sessionStorage に再オープン用フラグを保存し、1回だけ再読込してチャットを開いた状態へ戻します。

5. 管理画面

管理一覧では、会話の状態と制御項目をまとめて確認します。

項目	意味
名前	ユーザー表示名と、必要に応じて管理用名称を表示します。
最終更新日時	最後に会話や設定が更新された日時です。
🟢 NEW / 回答済み	ユーザーの新着投稿に管理者が未返信かどうかを示します。
👤 最終発言者	最後の発言がユーザーか管理者かを表示します。
⏱ 未返信時間	ユーザーの最終投稿から返信までの経過時間を把握します。
📌 ピン	重要なスレッドを上部または優先位置に固定するための状態です。
⭐ 重要	優先対応や注意が必要なスレッドに印を付けます。
💬 件数	例：`17(+2)`。総件数と未確認件数を表します。
最終ページURL	ユーザーが最後にチャットを使用したページです。
ユーザー通知	メール登録状態や通知可否を表示します。
履歴非表示	ユーザー側のメッセージ履歴を隠します。
UI非表示	チャットランチャー自体を隠します。
投稿停止	新規投稿を止めます。
注意	管理者だけが見るメモや注意コメントです。

6. ファイル共有・アップロード

管理者からユーザーへ

管理画面からファイルをアップロードすると、推測されにくい共有トークン付きURLを発行します。画像はサムネイル表示、その他は添付リンクとして表示します。

ユーザーから管理者へ

file_upload_allowed が有効な場合のみ、ファイル選択欄を表示します。大きなファイルは1MB単位などのチャンクに分割し、進捗を表示しながら送信します。

想定拡張子：jpg, jpeg, png, gif, webp, pdf, zip, txt, csv, xlsx, docx, mp4, mov

注意：拡張子だけでなく、MIMEタイプ、実ファイル内容、ファイルサイズ、保存先、実行権限も必ず検証してください。アップロード先ではPHP等を実行不可にします。

7. メール通知

通知は「登録・変更・削除」と「管理者返信時通知」を分けて考えます。

ユーザーはメールアドレスを登録・変更・削除できます。
管理者返信時だけユーザーへ通知します。
ユーザー投稿のたびに管理者へ通知するかは、運用設定で決めます。
メール本文には個人情報や共有トークンを必要以上に含めません。

メール不達時は、PHPの送信結果だけでなく、迷惑メール判定、SPF・DKIM・DMARC、Return-Path、サーバーの送信制限も確認します。

8. 設置方法

基本

<script src="/chat/chat.js" defer></script>

各ページの <head> または <body> 終了前に読み込みます。 chat.js は自身のURLからベースパスを求め、api/ 配下へアクセスします。

時間帯で表示する例

<?php
$now = (int)date('Hi');
if ($now >= 830 && $now <= 2000):
?>
<script src="/chat/chat.js" defer></script>
<?php endif; ?>

初期確認

チャットランチャーが表示される。
初回登録が完了する。
投稿後に1回だけ再読込される。
管理画面にNEWとして表示される。
管理者返信後にユーザー画面へ反映される。

9. 推奨ファイル構成

chat/
├─ chat.js
├─ admin.php
├─ admin_action.php
├─ config.php
├─ lib.php
├─ api/
│  ├─ register.php
│  ├─ messages.php
│  ├─ post.php
│  ├─ email.php
│  └─ upload.php
├─ data/
│  ├─ users.json
│  ├─ messages.json
│  ├─ settings.json
│  └─ logs/
├─ uploads/
│  └─ .htaccess
└─ assets/
   ├─ css/
   └─ images/

ファイル	担当
chat.js	ランチャー生成、登録、取得、投稿、通知設定、アップロードUI。
register.php	端末キー確認と表示名登録。
messages.php	スレッド情報、履歴、各種表示設定を返します。
post.php	ユーザー投稿を検証して保存します。
email.php	通知先メールの登録・変更・削除を処理します。
upload.php	分割アップロード、結合、検証、共有情報生成。
admin.php	スレッド一覧、返信、状態管理。
admin_action.php	管理画面の更新、返信、制御設定。
lib.php	JSON読書き、認証、日時、検証などの共通処理。

10. API概要

API	主な入力	主な出力
register.php	device_key, display_name	registered, csrf_token, limits
messages.php	device_key	messages, posting_allowed, thread_visible, widget_title, file_upload
post.php	csrf_token, title, body, page_url	success, message_id
email.php	action, email, csrf_token	enabled, masked_email
upload.php	chunk, chunk_index, total_chunks, filename	progress, file_id, share_url

実際のパラメータ名・レスポンス形式は現行コードを優先してください。APIは必ずJSONレスポンスと適切なHTTPステータスを返す構成に統一すると保守しやすくなります。

11. データ構造

サンプルはZIP内の sample/ に収録しています。

ユーザー／スレッド情報

{
  "device_abc123": {
    "display_name": "テストユーザー",
    "admin_name": "",
    "created_at": "2026-07-30 12:00:00",
    "updated_at": "2026-07-30 12:20:00",
    "posting_allowed": true,
    "thread_visible": true,
    "widget_visible": true,
    "file_upload_allowed": false,
    "email": {
      "enabled": false,
      "masked_email": ""
    }
  }
}

メッセージ

{
  "device_abc123": [
    {
      "id": "msg_001",
      "sender": "user",
      "title": "質問があります",
      "body": "詳しい内容です。",
      "page_url": "https://example.com/page/",
      "created_at": "2026-07-30 12:20:00"
    }
  ]
}

12. セキュリティ

管理画面はログイン認証またはBasic認証で保護します。
POST処理にはCSRFトークンを使用します。
表示時は必ずHTMLエスケープします。
JSON書込みは排他ロックと一時ファイル経由の置換を推奨します。
共有URLのトークンは十分に長いランダム値を使用します。
アップロードディレクトリではスクリプト実行を禁止します。
メールアドレスや端末キーをログへ過剰に残しません。

uploads/.htaccess 例

Options -Indexes

<FilesMatch "\.(php|phtml|phar|cgi|pl|py|sh)$">
  Require all denied
</FilesMatch>

13. カスタマイズ

タイトル

widgetTitle や管理設定からランチャー・ヘッダー名を変更します。

色

CSS変数に集約すると、ブランドカラー変更が安全です。

文字数

name 50、title 50、body 300をサーバー・JSの両方で一致させます。

アップロード

許可拡張子、最大容量、チャンクサイズを設定値として管理します。

画面側だけの制限は安全対策になりません。必ずPHP側でも同じ条件を検証してください。

14. 運用チェックリスト

管理画面の未返信を毎日確認する。
重要スレッドにはピンまたは重要マークを付ける。
JSONとアップロードファイルを定期バックアップする。
不要な共有ファイルと古いトークンを削除する。
メール通知が正常に届くか定期テストする。
投稿停止・UI非表示・履歴非表示の状態を誤設定していないか確認する。

15. トラブルシューティング

症状	確認点
ランチャーが出ない	chat.jsのURL、読み込みエラー、時間帯条件、UI非表示設定、CSPを確認。
登録できない	register.phpのHTTPステータス、JSON破損、dataディレクトリ権限を確認。
投稿後に戻らない	sessionStorageの再オープンフラグとreload処理の位置を確認。
管理画面に反映されない	post.phpの保存先、端末キー、キャッシュ、JSONロックを確認。
メールが届かない	送信ログ、迷惑メール、SPF/DKIM/DMARC、From/Return-Pathを確認。
画像が表示されない	共有トークン、previewパラメータ、MIME、権限、実ファイル有無を確認。
スマホで操作しづらい	viewport、タップ領域、固定要素、スクロール領域、iOS Safariの高さを確認。

16. 更新履歴

段階	主な内容
V1	端末識別、表示名登録、スレッド式投稿、右下ランチャー。
V2	通知、投稿許可、履歴表示、UI表示、注意コメントなど運用機能。
V3	管理一覧、NEW、最終発言者、未返信時間、ピン、重要、件数表示。
拡張	管理者共有ファイル、画像サムネイル、ユーザー分割アップロード。
Ver.1.0 Manual	2026-07-30：公式マニュアル初版。

ページに寄り添う、軽量なサポートチャット。

1. Smart Chatとは

ユーザーにやさしい

管理しやすい

設置しやすい

育てやすい

2. 設計思想

ページではなく、端末に会話を持たせる

ユーザー側は親しみやすく、管理側は情報量を優先

小規模運用に合うJSON構成

3. 利用の流れ

4. ユーザー画面

5. 管理画面

6. ファイル共有・アップロード

管理者からユーザーへ

ユーザーから管理者へ

7. メール通知

8. 設置方法

基本

時間帯で表示する例

初期確認

9. 推奨ファイル構成

10. API概要

11. データ構造

ユーザー／スレッド情報

メッセージ

12. セキュリティ

uploads/.htaccess 例

13. カスタマイズ

タイトル

色

文字数

アップロード

14. 運用チェックリスト

15. トラブルシューティング

16. 更新履歴

ページに寄り添う、
軽量なサポートチャット。