type=metrics:エージェント別・チャネル別の集計値(会話数、人間への転送、AI による対応完結、通話時間、WhatsApp 通知、再接触、日別・時間別の系列)。レポートやダッシュボード向けです。type=chats:会話ごとに 1 行、すべてのパラメータを含み、ページ分割されます。生データのエクスポートや突き合わせ向けです。
🔑 認証
すべてのリクエストにはanalytics_api 権限を持つ API キーが必要です。Lovi のプロフィール(プロフィール → API Key)から、アナリティクス(API) 権限を有効にして作成してください。Web ウィジェットで使うキーとは別のものです。
キーは x-api-key ヘッダー(推奨)または URL パラメータ access_key で送信します。
会社は常にキーから決まります。キーは自社のデータしか読み取れず、別の会社を指定するパラメータはありません。
エンドポイント
URL パラメータ
日付は
tz で解釈されます。tz=Europe/Madrid で date_from=2026-10-01&date_to=2026-10-31 を指定すると、マドリード時間の 10 月 1 日 00:00 から 11 月 1 日 00:00 までが対象です。夏時間の切り替えも考慮されます。
レスポンス内の日時はすべて UTC(Z で終わる ISO 8601)です。
指標(type=metrics)
エージェントとチャネルの組み合わせごとに 1 件を返し、会話数の多い順に並べます。
会話(type=chats)
範囲内の会話を古い順に 1 件ずつ返します。既定では 1 ページあたり 100 件です。終了した会話(ended_at があるもの)のみを含みます。まだ開いている会話は、終了するまで表示されません。
ページ分割
next_cursor が null でない間は、同じパラメータに cursor=<next_cursor> を加えて次のページを取得してください。会話は created_at と id の順に並ぶため、ページ間で重複や欠落はありません。
エラー
エラーは JSON{ "success": false, "message": "…" } を返します。
制限とベストプラクティス
- 1 リクエストあたり最大 31 日、1 ページあたり最大 100 件の会話。
- 1 か月分の
metricsリクエストは数秒かかります。月次・日次レポートには期間ごとに 1 回の呼び出しで十分で、ループで問い合わせる必要はありません。 - 1 か月分の会話をエクスポートする場合は、並列ではなく 1 ページずつ順番に取得してください。
- キーは秘密にし、サーバー側で保管してください。ブラウザやモバイルアプリでは使用しないでください。
