JavaScript API

window.CarePort のグローバル API・インスタンスメソッド・イベント

スクリプト読み込み後、グローバルに window.CarePort が公開されます。データ属性では渡せないユーザー情報・コールバック・イベント購読はこの API を使います。

補足: window.CarePort はスクリプトが読み込まれた後に利用可能になります。next/script を使う場合は onLoad コールバック内、Vanilla の場合はスクリプトの後でアクセスしてください。

グローバル API

CarePort.init(options)

ウィジェットを初期化してマウントします。データ属性による自動初期化の代わりに、JavaScript で完全に制御したい場合に使います。生成されたインスタンスを返します。

const widget = window.CarePort.init({
  apiKey: 'cp_live_xxxxxxxxxxxxxxxx', // 必須
  botId: '00000000-0000-0000-0000-000000000000',
  accentColor: '#635BFF',
  position: 'bottom-right',
  language: 'ja',
  welcomeMessage: 'ご質問はありますか？',
  quickReplies: ['料金について', 'デモを予約', 'サポート'],
  user: {
    id: 'user_123',
    name: '山田 太郎',
    email: 'taro@example.com',
  },
  onReady: () => console.log('widget ready'),
  onMessage: (message) => console.log('received', message),
});

主なオプション（抜粋）:

オプション	型	説明
`apiKey`	string	必須。`cp_live_` / `cp_test_` キー
`botId`	string	ボット ID（UUID）
`accentColor`	string	アクセントカラー（hex）
`position`	`bottom-right` / `bottom-left`	表示位置
`language`	`ja` / `en`	言語
`welcomeMessage`	string	ウェルカムメッセージ
`quickReplies`	string[]	クイックリプライ候補
`autoOpenDelay`	number	自動オープン遅延（ミリ秒）
`user`	WidgetUser	ユーザー情報（`id` / `name` / `email` / `phone` / `metadata`）
`container`	HTMLElement	マウント先（省略時は `document.body`）
`onReady` / `onOpen` / `onClose`	function	ライフサイクルコールバック
`onMessage`	function	メッセージ受信コールバック
`onError`	function	エラーコールバック

注意: データ属性の data-auto-open は秒ですが、JavaScript API の autoOpenDelay はミリ秒です。

CarePort.mount(apiKey, options?)

init() の簡易版。第 1 引数に API キー、第 2 引数にそれ以外のオプションを渡します。

const widget = window.CarePort.mount('cp_live_xxxx', {
  botId: '00000000-0000-0000-0000-000000000000',
  position: 'bottom-left',
});

CarePort.getInstance()

現在マウントされているインスタンスを返します（未マウント時は null）。

const widget = window.CarePort.getInstance();
widget?.open();

CarePort.version

ウィジェットのバージョン文字列。

インスタンスメソッド

init() / mount() / getInstance() が返すインスタンスには以下のメソッドがあります。

メソッド	説明
`open()`	チャットウィンドウを開く
`close()`	チャットウィンドウを閉じる
`toggle()`	開閉をトグルする
`sendMessage(text)`	メッセージをプログラムから送信する
`setUser(user)`	ユーザー情報を後から設定・更新する
`on(event, callback)`	イベントを購読する
`off(event, callback)`	イベント購読を解除する
`destroy()`	ウィジェットを破棄して DOM から取り除く

const widget = window.CarePort.getInstance();

widget.open();
widget.sendMessage('営業時間を教えてください');
widget.setUser({ id: 'user_123', name: '山田 太郎' });

イベント

on() / off() で購読できるイベント名は以下のとおりです。

イベント	発火タイミング
`ready`	ウィジェットの初期化完了
`open` / `close`	ウィンドウの開閉
`message:sent`	ユーザーがメッセージを送信
`message:received`	AI / オペレーターから返信を受信
`escalation`	有人対応へエスカレーション
`connection:change`	接続状態の変化
`session:start` / `session:restore`	セッションの開始・復元
`proactive:show` / `proactive:click` / `proactive:dismiss` / `proactive:convert`	プロアクティブメッセージ関連
`error`	エラー発生

const widget = window.CarePort.getInstance();

widget.on('message:received', (payload) => {
  console.log('AI からの返信:', payload);
});

widget.on('escalation', () => {
  // 有人対応に切り替わったときの処理
});