ドキュメント
Ontara をサイトに導入し、どんな言語の訪問者にも返信するために必要なことをまとめています。
ウィジェットの導入
ログインしてワークスペースを作成したら、管理画面のチャットウィジェットを開きます。表示されたコードをコピーし、すべてのページの </body> の直前に貼り付けてください。
<script src="https://YOUR-LINGLY-HOST/w.js" data-site="pk_your_site_key" async></script>ウィジェットは登録したドメインとそのサブドメインでのみ動作します(たとえば example.com を登録すると shop.example.com も含まれます)。導入前に、管理画面からテストページを開いて試せます。
WordPress
Ontara の WordPress プラグインを入れるか、ヘッダー・フッターにスクリプトを追加できる任意のプラグインで同じコードを貼り付けてください。
シングルページアプリ
HTML テンプレートに 1 回追加するだけです。クライアント側でルートが切り替わっても動作し続けます。
JavaScript API
スクリプトが読み込まれると、小さなグローバルオブジェクトが使えるようになります。
| 呼び出し | 動作 |
|---|---|
lingly.open() | チャット画面を開きます。独自の「お問い合わせ」ボタンなどから呼び出せます。 |
lingly.close() | チャット画面を閉じます。 |
lingly.identify({ userId, email, name, hash }) | 訪問者が誰かを Ontara に伝えます。本人確認を参照してください。 |
lingly.reset() | 訪問者の情報を消去します。ユーザーがログアウトしたときなどに使います。 |
lingly.shutdown() | ページからウィジェットを取り除きます。 |
翻訳
チームでチームの言語を設定します。訪問者が別の言語で書くと、メッセージはチーム向けに翻訳され、原文もワンクリックで確認できます。あなたの返信は、訪問者の言語に翻訳されてから届きます。ウェルカムメッセージや自動返信も翻訳されます。
翻訳のオン・オフは自動化で切り替えます。ウィジェット自体のボタンは訪問者のブラウザの言語(英語、中国語、スペイン語、ポルトガル語、フランス語、ドイツ語、日本語、韓国語、イタリア語)に合わせて表示されるほか、言語を固定することもできます。
AI 回答
- ナレッジベースに内容を追加します。質問と回答、Web ページの URL、テキストのいずれでも構いません。
- 同じページのAI を試すで、どう答えるかを確認します。
- 自動化で AI が答えるタイミングを選びます。誰もオンラインでないときだけか、常に最初に答えるかです。
AI はナレッジベースだけをもとに、訪問者の言語で答えます。答えられないときや訪問者が担当者を求めたときは会話をチームに引き継ぎ、その会話ではそれ以上答えません。チームのメンバーが返信した時点でも AI は止まります。
不在時の対応
- 不在メッセージ:チームの誰もオンラインでないときに自動で送られます。
- メールアドレスの取得:ウィジェットが訪問者にメールアドレスを尋ねます(尋ねない、不在時のみ、常に、から選べます)。
- メールでのフォローアップ:訪問者がページを離れていてメールアドレスがわかっている場合、返信は約 2 分後にメールで届きます。
- チームへの通知:訪問者が数分待っても誰もオンラインでない場合、メール通知をオンにしているメンバーに知らせが届きます。
チームと権限
| 権限 | できること |
|---|---|
| オーナー | 請求を含むすべての操作。 |
| 管理者 | 設定、ナレッジベース、サイト、招待、請求。 |
| 担当者 | 会話への返信とナレッジベースの閲覧。 |
チームからメンバーを招待します。招待されたメールアドレスでログインすると参加できます。どのプランも担当者数は無制限です。
プランと上限
各プランの内容は料金をご覧ください。月間の上限に達してもライブチャットはそのまま使えます。AI 回答と翻訳は翌月かアップグレードまで一時停止します。プランの保存期間を過ぎた会話は自動的に削除されます。
本人確認
訪問者があなたのサイトにログインしている場合、その人が誰かを Ontara に伝えて証明できます。これで誰もあなたのユーザーになりすませなくなります。
- チャットウィジェット → 本人確認でオンにし、シークレットをコピーします。シークレットはサーバーにだけ置いてください。
- サーバーで
hex(HMAC-SHA256(secret, userId))を計算します。 - ページで
lingly.identify({ userId, email, name, hash })を呼び出します。
// Node.js
import { createHmac } from "node:crypto";
const hash = createHmac("sha256", process.env.LINGLY_IDENTITY_SECRET).update(user.id).digest("hex");
// PHP
$hash = hash_hmac('sha256', $userId, getenv('LINGLY_IDENTITY_SECRET'));担当者には訪問者の横に認証済みのバッジが表示されます。hash が正しくない呼び出しは拒否されます。チャットでメールアドレスを入力しただけの訪問者は認証済みになりません。
メールでの返信
ページを離れた訪問者に返信がメールで届いたら、訪問者はそのメールに返信するだけで構いません。返信は同じ会話に表示され、引用部分や署名は取り除かれます。
これには受信用のドメインが必要です。Cloudflare Email Routing で r-*@reply.your-domain.com を Ontara の Worker に転送し、INBOUND_EMAIL_DOMAIN=reply.your-domain.com を設定してください。会話に投稿できるのは訪問者本人のアドレスだけで、自動返信や不達メールは無視されます。
通知
各メンバーはアカウント → ブラウザ通知で、使っているデバイスの通知をオンにできます。受信箱を開いていないときに訪問者がメッセージを送ると通知が表示され、クリックすると会話が開きます。チームのメール通知も引き続きバックアップとして機能します。
React
@lingly/react をインストールし、ルートに <LinglyChat siteKey="pk_..." user={...} /> を置いて、useLingly() から open、close、identify、reset を取得します。ユーザーがログアウトして user が null になると、ウィジェットはその訪問者の情報を消去します。このパッケージはまだ npm に公開されていません。公開までは、上の JavaScript API で同じことができます。
WordPress
- プラグインをダウンロードし、WordPress のプラグイン → 新規追加 → プラグインのアップロードからアップロードします。
- 有効化して設定 → Ontara Chatを開きます。
- サイトキーを貼り付けます。本人確認のシークレットも貼り付けると、ログイン中の WordPress ユーザーが認証済みとして表示されます。
REST API
開発者でキーを作成し、すべてのリクエストに Authorization: Bearer lk_... を付けて送ります。サイト一覧、会話の一覧と詳細、メッセージの取得、チームとしての返信(訪問者向けに自動翻訳)、会話のクローズと再開、会話の削除、訪問者の詳細を取得できます。キーごとに毎分 120 リクエストまでです。詳しい仕様は英語版をご覧ください。
Webhook
開発者で https のエンドポイントを追加し、受け取るイベントを選びます。各イベントは JSON で POST され、Lingly-Signature: t=タイムスタンプ,v1=署名 ヘッダーが付きます。署名は hex(HMAC-SHA256(secret, t + "." + rawBody)) です。2xx を返せば成功とみなされ、失敗した配信は約 20 分間再試行されます。失敗が続くエンドポイントは一時停止されます。同じイベントがまれに 2 回届くことがあるので、id で重複を除いてください。