導入ガイド

アクセサリ埋め込み

ウェブサイトにチャットペグを埋め込むには、一行のコードのみが必要です。

埋込コードの取得

マーチャントバックエンドにログイン → チャネル設定 → 埋込コード から、ご自身の専用の埋込コードをコピーしてください：

<script>
  window.$aicrs = window.$aicrs || { q: [] };
</script>
<script async src="https://your-support-domain.com/widget/loader.js" data-wk="YOUR_WIDGET_KEY"></script>

このコードを、ウェブサイトのすべてのページで </body> タグの前に貼り付けてください。ペグはページの右下にチャットのバブルとして表示され、訪問者がクリックするとカスタマーサポートが開始されます。

ドメインホワイトリスト

ペグの盗用を防止するため、ペグはご登録済みのドメインでのみ動作します。マーチャントバックエンド → チャネル設定 → ドメインホワイトリスト にウェブサイトのドメインを追加してください（複数のドメインもサポートします）。登録されていないドメインではペグが静かに失敗し、ページには影響を与えません。

widget_key のリセット

key が漏洩している可能性がある場合は、チャネル設定からリセット可能です。リセット後、古い key は即座に無効となり、ウェブサイト上の埋込コードも更新する必要があります。

よくあるご質問

• ペグが表示されない？ 現在のドメインがホワイトリストに含まれているか、widget_key がバックエンドと一致しているか、アカウントが有効期間内にあるかを確認してください。
• ウェブサイトの速度に影響は？ ローダーは1KB未満で非同期読み込みを行うため、ページのレンダリングを妨げません。

メンバーシップの連携を識別する

ユーザーがウェブサイトにログインすると、identify を呼び出して会員情報を入力することで、カスタマーサポートシステムはそのブラウザのセッションをその会員名下に統合します。オペレーターは会員の身元を直接確認でき、複数デバイスからのアクセスも同じ訪問者として統合されます。

呼び出し方法

ページでユーザーがログインしていることを確認したら、次のように呼び出してください：

$aicrs.identify({
  externalId: 'U10086',      // 必須、ご自身のシステム内でのユーザーの唯一識別子
  name: '山田花子',             // 省略可、表示名
  phone: '138****0000',      // 省略可
  email: 'user@example.com', // 省略可
  hash: 'サービス側で計算したHMAC署名',  // 必須、なりすまし防止
  custom: { vip: 'gold' }     // 省略可、追加フィールド、オペレーター側で表示されます
})

署名アルゴリズム

hash は必ずサービス側で計算してください（widget_secret はフロントエンドコードに現れてはなりません）：

hash = HMAC-SHA256(widget_secret, externalId) の16進数小文字

widget_secret は、管理者ポータル → チャンネル設定 → 埋込コード で確認でき、widget_key と同時にリセットされます。

Node.js のサンプル：

const crypto = require('crypto')
const hash = crypto.createHmac('sha256', WIDGET_SECRET).update(externalId).digest('hex')

確認結果

署名の確認に成功した訪問者はオペレーター側に「認証済み」という表示がされます。確認に失敗した場合は identify の呼び出しが無視され、匿名のまま保持され、ページにエラーが発生したり中断したりすることはありません。

Webhookイベントプッシュ

システムは重要なビジネスイベントが発生した際に、ご設定されたコールバックアドレスにJSONメッセージをプッシュし、カスタマーサポートのデータを自社システムに同期しやすくします。

設定

管理者用Webサイト → データとシステム → Webhook：コールバックURL（HTTPS必須）と署名シークレットsecretを入力し、購読するイベントタイプを選択します。保存後、「テストイベントの送信」をクリックして即時連携調整が可能です。

リクエスト形式

各プッシュは1つのPOSTリクエストです：

POST ご指定のコールバックURL
Content-Type: application/json
X-AICRS-Event: イベントタイプ
X-AICRS-Signature: HMAC-SHA256(secret, リクエストボディ) 十六進数小文字

リクエストボディの構造：

{
  "event": "message.created",
  "tenant_id": 129,
  "timestamp": 1784500000,
  "data": { "オブジェクトスナップショット": "..." }
}

イベントタイプ

署名検証と再試行

プッシュを受信後は、secretを使用してリクエストボディのHMAC-SHA256を計算し、X-AICRS-Signatureと照合してください。一致しない場合は破棄してください。

インターフェースが2xxを返すと成功とみなされます。失敗した場合は 1分 / 5分 / 15分 間隔で再試行を3回実施します。それでも失敗した場合、失敗ステータスとなり、管理者用Webサイトの配信記録で失敗理由を確認し、手動でトラブルシューティングできます。

オープンAPI

オープンAPIは、あなたのシステムからカスタマーサポートデータを読み出し、チケットを作成し、テナントごとに分離するために使用されます。

認証

管理者バックエンド → データとシステム からAPIキーを生成します（ak_で始まる形式、平文は生成時に一度だけ表示されるので、慎重に保存してください；リセット後は旧キーは直ちに無効になります）。

すべてのリクエストには以下のリクエストヘッダーを指定してください：

Authorization: Bearer ak_あなたのKey

速度制限

各キーは60秒以内に最大で120回のリクエストが可能です。これ以上送信すると429が返されます。

エンドポイント一覧

例：

curl -H "Authorization: Bearer ak_xxx" \
  "https://あなたのカスタマーサポートドメイン/api/open/v1/conversations?page=1"

説明

• すべての応答はJSON形式で返されます。リストのインターフェースはpageパラメータでページネーションをサポートしています。
• 現在のバージョンでは、APIを通じて訪問者にメッセージを送信することはできません。
• テナントが無効化されるかサービス期間が満了すると、APIも同時に停止されます。

エラーコード一覧

すべてのインターフェースのエラーレスポンスは、JSON構造で統一されています：

{ "code": "エラーコード", "message": "中国語のヒント" }

HTTP ステータスコードと code の対応関係：

処理の推奨：

• 401/403: Keyが有効か、アカウントのサービス状態を確認してください。
• 429: Retry-After またはバックオフ戦略に従って、後で再試行してください。
• 5xx: 指数関数的インターフェースでは安全に再試行できます。非イデムな操作の場合は、確認後に再試行してください。

CRMオープンインターフェース

顧客および商談データの読み書きはオープンAPI（/api/open/v1、Bearer ak_ キー、管理者バックエンド"データとシステム → API"で生成）を使用します。

顧客

重複規則は管理画面と同じです：external_id > 電話番号 > メールアドレス、一致すれば既存顧客にマージし、重複して登録しません。

制限頻度：各Key 60秒あたり120回、それ以上は429を返します。

顧客イベントプッシュ通知

顧客ライフサイクルイベントは、Webhook経由で通知されます（マーチャントバックエンドの「データとシステム → Webhook」でサブスクリプションを設定）。署名および再試行メカニズムはメッセージイベントと一致しており、X-AICRS-Signature（HMAC-SHA256）、および指数バックオフ方式の再試行が使用されます。

ペイロード形式：{"event":"customer.created","data":{...顧客オブジェクト...},"ts":1690000000}。2xxステータスコードを返すと確認されます。非2xxステータスコードまたはタイムアウトが発生した場合は、バックオフ戦略に従って再試行されます。