メインコンテンツへスキップ
アナリティクス API は、貴社の会話データを返す読み取り専用のエンドポイントです。2 つのモードがあります。
  • 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 件を返し、会話数の多い順に並べます。
前月との比較:月ごとに 1 回ずつ、計 2 回エンドポイントを呼び出し、差を計算してください。 人間のエージェントがいる日のみの対応完結率:daily を使い、escalated > 0 の日だけを残してください。

会話(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 ページずつ順番に取得してください。
  • キーは秘密にし、サーバー側で保管してください。ブラウザやモバイルアプリでは使用しないでください。