> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lovi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# アナリティクス API

> 会話のアナリティクスを取得します：エージェント別・チャネル別の集計指標と、各会話の詳細

アナリティクス API は、貴社の会話データを返す読み取り専用のエンドポイントです。2 つのモードがあります。

* **`type=metrics`**：エージェント別・チャネル別の集計値（会話数、人間への転送、AI による対応完結、通話時間、WhatsApp 通知、再接触、日別・時間別の系列）。レポートやダッシュボード向けです。
* **`type=chats`**：会話ごとに 1 行、すべてのパラメータを含み、ページ分割されます。生データのエクスポートや突き合わせ向けです。

## 🔑 認証

すべてのリクエストには **`analytics_api`** 権限を持つ API キーが必要です。Lovi のプロフィール（**プロフィール → API Key**）から、**アナリティクス（API）** 権限を有効にして作成してください。Web ウィジェットで使うキーとは別のものです。

キーは `x-api-key` ヘッダー（推奨）または URL パラメータ `access_key` で送信します。

```bash theme={null}
curl -H "x-api-key: YOUR_API_KEY" \
  "https://cloud.lovi.ai/functions/v1/analytics?type=metrics&date_from=2026-10-01&date_to=2026-10-31"
```

> [!NOTE]
>
> 会社は常にキーから決まります。キーは自社のデータしか読み取れず、別の会社を指定するパラメータはありません。

## エンドポイント

```
GET https://cloud.lovi.ai/functions/v1/analytics
```

### URL パラメータ

| パラメータ | 必須 | 説明 |
| - | - | - |
| `type` | はい | `metrics` または `chats`。 |
| `date_from` | はい | 開始日、`YYYY-MM-DD`、当日を含む。 |
| `date_to` | はい | 終了日、`YYYY-MM-DD`、当日を含む。範囲は最大 **31 日** です。 |
| `tz` | いいえ | 日付の解釈と日別・時間別の系列の作成に使う IANA タイムゾーン。既定値は `Europe/Madrid`。例：`UTC`、`America/Bogota`。 |
| `channels` | いいえ | カンマ区切りのチャネル：`voice`、`whatsapp`、`web`、`instagram`、`facebook`… |
| `agents` | いいえ | カンマ区切りのエージェント ID（UUID）。 |
| `languages` | いいえ | カンマ区切りのユーザーの言語コード。例：`es,pt`。 |
| `limit` | いいえ | `chats` のみ。1 ページあたりの会話数、1〜100。既定値は 100。 |
| `cursor` | いいえ | `chats` のみ。前のページが返した `next_cursor`。 |

日付は `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 件を返し、会話数の多い順に並べます。

```bash theme={null}
curl -H "x-api-key: YOUR_API_KEY" \
  "https://cloud.lovi.ai/functions/v1/analytics?type=metrics&date_from=2026-10-01&date_to=2026-10-31&channels=voice"
```

```json theme={null}
{
  "tz": "Europe/Madrid",
  "from": "2026-09-30T22:00:00.000Z",
  "to": "2026-10-31T23:00:00.000Z",
  "data": [
    {
      "agent": { "id": "2fef9696-0662-4e49-bb83-7564ff25c7ef", "name": "Voice assistant" },
      "channel": "voice",
      "conversations": 12480,
      "escalated": 4120,
      "contained_pct": 67.0,
      "avg_duration_s": { "all": 109, "without_transfer": 120, "with_transfer": 86 },
      "whatsapp_notifications": 1210,
      "unique_users": 7950,
      "recontacts": 2480,
      "daily": [
        { "date": "2026-10-01", "conversations": 410, "escalated": 151 }
      ],
      "hourly": [
        { "hour": 9, "conversations": 1320 },
        { "hour": 10, "conversations": 1544 }
      ]
    }
  ]
}
```

| フィールド | 説明 |
| - | - |
| `agent` | 会話を担当した AI エージェント（`id`、`name`）。会話にエージェントがない場合は `null`。 |
| `channel` | 会話のチャネル。記録されていない場合は `n/a`。 |
| `conversations` | 範囲内に開始された会話数（音声では通話数）。 |
| `escalated` | 人間に転送された会話数（`chat_escalated` イベントがあるもの）。 |
| `contained_pct` | `(conversations − escalated) / conversations × 100`。転送せずに AI が対応した割合です。**解決率ではありません。** |
| `avg_duration_s` | 通話の平均時間（秒）：全体、転送なし、転送あり。時間を持たないチャネルでは `null`（時間を記録するのは音声のみ）。 |
| `whatsapp_notifications` | それらの会話から送信された WhatsApp 通知数（`notification_sent` イベント）。 |
| `unique_users` | 異なるユーザー数（音声では異なる電話番号の数）。 |
| `recontacts` | 範囲内に 2 件以上の会話があるユーザー数。再接触率 = `recontacts / unique_users`。 |
| `daily` | `tz` での日別の会話数と転送数。会話のない日は含まれません。 |
| `hourly` | `tz` での時間帯別（0〜23）の会話数。会話のない時間帯は含まれません。 |

> [!TIP]
>
> **前月との比較**：月ごとに 1 回ずつ、計 2 回エンドポイントを呼び出し、差を計算してください。
> **人間のエージェントがいる日のみの対応完結率**：`daily` を使い、`escalated > 0` の日だけを残してください。

## 会話（`type=chats`）

範囲内の会話を古い順に 1 件ずつ返します。既定では 1 ページあたり 100 件です。**終了した**会話（`ended_at` があるもの）のみを含みます。まだ開いている会話は、終了するまで表示されません。

```bash theme={null}
curl -H "x-api-key: YOUR_API_KEY" \
  "https://cloud.lovi.ai/functions/v1/analytics?type=chats&date_from=2026-10-01&date_to=2026-10-01&channels=voice&limit=100"
```

```json theme={null}
{
  "data": [
    {
      "id": "29d67962-119b-406c-b172-d66cf179975e",
      "created_at": "2026-10-01T05:58:40.4431Z",
      "ended_at": "2026-10-01T05:58:48Z",
      "last_message_at": null,
      "status": "aiagent",
      "channel": "voice",
      "phone": "34600000000",
      "language": "es",
      "agent": { "id": "2fef9696-0662-4e49-bb83-7564ff25c7ef", "name": "Voice assistant" },
      "escalated_to_human": true,
      "escalated_at": "2026-10-01T05:58:45.12Z",
      "attended_by_human": false,
      "human_agents": [],
      "whatsapp_notifications": 0,
      "inquiry_set": null,
      "parameters": {
        "channel": "voice",
        "call_length": 8,
        "phone_call": "+34600000000",
        "voice_inbound": true,
        "conversation_recording_url": "https://…"
      }
    }
  ],
  "next_cursor": "MjAyNi0xMC0wMVQwNjowMjoxMS4xMjM0NTZ8…"
}
```

| フィールド | 説明 |
| - | - |
| `id` | 会話の ID。 |
| `created_at`、`ended_at`、`last_message_at` | 開始、終了、最後のメッセージの日時（UTC）。 |
| `status` | 会話の担当：`aiagent`、`human`、`queue`（人間を待機中）、`push`（通知から開始）。 |
| `channel`、`language` | 便宜上 `parameters.channel` と `parameters.lang_user` からコピーしたもの。通話で `channel` が保存されていない場合は `voice` を返します。 |
| `phone` | 連絡先の電話番号。数字のみで `+` なし（E.164 形式）。会話に番号がない場合（例：Web ウィジェット）は `null`。 |
| `agent` | 会話の AI エージェント（`id`、`name`）。 |
| `escalated_to_human`、`escalated_at` | 人間に転送されたかどうかと、その日時（最初の転送）。 |
| `attended_by_human` | 人間のエージェントが少なくとも 1 件メッセージを書いたかどうか。 |
| `human_agents` | 会話に書き込んだ人間のエージェント（`id`、`name`）。`attended_by_human` が `true` でも空の場合があります。外部 CRM から送られたメッセージは個人に紐付けられないためです。 |
| `whatsapp_notifications` | 会話から送信された WhatsApp 通知数。 |
| `inquiry_set` | 会話の発生元となった送信キャンペーン（inquiry set）：`id` と `name`（送信作成時に付けた名前）。送信から発生した会話でない場合は `null`。キャンペーンが既に存在しない場合、`name` は `null` になることがあります。 |
| `parameters` | 会話に保存された**すべての**パラメータ（フィルタなし）。キーはチャネルとエージェントの設定によって異なります（音声：`call_length`、`phone_call`、`voice_inbound`、`session_call_id`、`conversation_recording_url`…、およびエージェントが保存する独自パラメータ）。送信から発生した会話では、`parameters.inquiry_set_id` にキャンペーンの**名前**が入り、ID は `inquiry_set.id` にあります。 |

### ページ分割

`next_cursor` が `null` でない間は、同じパラメータに `cursor=<next_cursor>` を加えて次のページを取得してください。会話は `created_at` と `id` の順に並ぶため、ページ間で重複や欠落はありません。

```python theme={null}
import requests

URL = "https://cloud.lovi.ai/functions/v1/analytics"
HEADERS = {"x-api-key": "YOUR_API_KEY"}
params = {"type": "chats", "date_from": "2026-10-01", "date_to": "2026-10-31", "channels": "voice"}

chats = []
while True:
    page = requests.get(URL, headers=HEADERS, params=params, timeout=60).json()
    chats.extend(page["data"])
    if not page["next_cursor"]:
        break
    params["cursor"] = page["next_cursor"]

print(len(chats), "件の会話")
```

## エラー

エラーは JSON `{ "success": false, "message": "…" }` を返します。

| コード | 発生条件 |
| - | - |
| `400` | キーがない（`Missing access_key parameter`）、`type` が無効、日付が無効、範囲が 31 日を超える、または `tz`、`limit`、`agents`、`channels`、`cursor` が無効。 |
| `403` | キーは存在するが `analytics_api` 権限がない。 |
| `404` | キーが無効または失効している。 |
| `405` | `GET` 以外のメソッド。 |
| `500` | 内部エラー。数秒後に再試行してください。解決しない場合は、リクエストの時刻を添えてサポートにご連絡ください。 |

## 制限とベストプラクティス

* 1 リクエストあたり最大 **31 日**、1 ページあたり最大 **100 件**の会話。
* 1 か月分の `metrics` リクエストは数秒かかります。月次・日次レポートには期間ごとに 1 回の呼び出しで十分で、ループで問い合わせる必要はありません。
* 1 か月分の会話をエクスポートする場合は、並列ではなく 1 ページずつ順番に取得してください。
* キーは秘密にし、サーバー側で保管してください。ブラウザやモバイルアプリでは使用しないでください。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.