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

# Conversations

> Endpoints to view conversations

Endpoints to view conversation history.

## GET /tenants/{slug}/conversations

List conversations.

**Required scope:** `conversations:read`

### Request

```bash theme={null}
curl https://api.animam.ai/tenants/my-company/conversations \
  -H "Authorization: Bearer ak_your_token"
```

### Query Parameters

| Param       | Type   | Description                                    |
| ----------- | ------ | ---------------------------------------------- |
| `page`      | number | Page (default: 1)                              |
| `limit`     | number | Conversations per page (default: 20, max 100)  |
| `from`      | string | Start date (ISO 8601)                          |
| `to`        | string | End date (ISO 8601)                            |
| `channel`   | string | Filter by channel (`web`, `agent`, `voice`, …) |
| `segment`   | string | Filter by segment slug                         |
| `visitorId` | string | Filter by visitor profile id                   |
| `toolType`  | string | Only conversations that used this tool type    |

### Response

```json theme={null}
{
  "conversations": [
    {
      "id": "conv_abc123",
      "sessionId": "sess_xyz789",
      "createdAt": "2024-01-25T10:30:00Z",
      "messageCount": 8,
      "pageUrl": "/pricing",
      "channel": "web",
      "status": "BOT",
      "visitorType": "human",
      "segment": { "slug": "pricing", "name": "Pricing" },
      "intent": "What are your prices?",
      "firstUserMessage": "What are your prices?",
      "preview": "What are your prices?",
      "toolCallsCount": 2,
      "feedback": { "positive": 1, "negative": 0 },
      "toolHistory": [
        { "toolName": "submit_form", "toolType": "SUBMIT_FORM", "input": {}, "result": {}, "timestamp": "2024-01-25T10:44:00Z" }
      ]
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 156,
    "pages": 8
  }
}
```

<Note>
  `intent` / `firstUserMessage` expose the visitor's first message directly, and
  `toolCallsCount` is computed server-side (from the persisted `tool_history`,
  **MCP tool calls included**) — no need to fetch the full transcript to know what
  was asked or whether a tool fired.
</Note>

## GET /tenants/{slug}/conversations/{id}

Retrieve a complete conversation with all messages.

**Required scope:** `conversations:read`

### Request

```bash theme={null}
curl https://api.animam.ai/tenants/my-company/conversations/conv_abc123 \
  -H "Authorization: Bearer ak_your_token"
```

### Response

```json theme={null}
{
  "id": "conv_abc123",
  "sessionId": "sess_xyz789",
  "segment": "pricing",
  "startedAt": "2024-01-25T10:30:00Z",
  "lastMessageAt": "2024-01-25T10:45:00Z",
  "messages": [
    {
      "id": "msg_001",
      "role": "user",
      "content": "Hello, what are your prices?",
      "timestamp": "2024-01-25T10:30:00Z"
    },
    {
      "id": "msg_002",
      "role": "assistant",
      "content": "Hello! We offer 3 plans...",
      "timestamp": "2024-01-25T10:30:02Z"
    },
    {
      "id": "msg_003",
      "role": "user",
      "content": "And for the Pro plan?",
      "timestamp": "2024-01-25T10:31:00Z"
    }
  ],
  "metadata": {
    "userAgent": "Mozilla/5.0...",
    "referrer": "https://google.com",
    "page": "/pricing"
  }
}
```

## GET /tenants/{slug}/conversations/stats

Aggregated conversation analytics over a time window — the REST equivalent of the
MCP `get_bot_stats` overview, reachable with a plain tenant key (no MCP client
needed). Read-only and idempotent: ideal for a cron, dashboard or Grafana scrape.

**Required scope:** `stats:read` (the legacy `ak_…` tenant key carries it).

### Request

```bash theme={null}
curl "https://api.animam.ai/tenants/my-company/conversations/stats?from=2024-01-19" \
  -H "Authorization: Bearer ak_your_token"
```

<Note>
  Authenticate `ak_…` API tokens with **`Authorization: Bearer`**. The `X-API-Key`
  header is reserved for a tenant's legacy plain API key and returns `401` for an
  `ak_…` token.
</Note>

### Query Parameters

| Param         | Type   | Description                                               |
| ------------- | ------ | --------------------------------------------------------- |
| `from`, `to`  | string | ISO date window (default: last 30 days; capped to 1 year) |
| `granularity` | string | Timeline bucket: `day` (default), `week`, `month`         |
| `segment`     | string | Filter by segment slug                                    |
| `channel`     | string | Filter by channel (`web`, `agent`, …)                     |
| `window`      | string | `all` → also include all-time totals (`allTime`)          |

### Response

```json theme={null}
{
  "window": { "from": "2024-01-19T00:00:00Z", "to": "2024-02-18T00:00:00Z", "granularity": "day" },
  "totals": {
    "conversations": 4,
    "messages": 30,
    "escalated": 0,
    "avgMessagesPerConversation": 7.5,
    "withToolCalls": 3,
    "toolCallsTotal": 5
  },
  "satisfaction": { "positive": 0, "negative": 0, "rate": null },
  "timeline": [
    { "date": "2024-01-30", "conversations": 2, "messages": 10 },
    { "date": "2024-01-31", "conversations": 1, "messages": 4 }
  ],
  "byChannel": { "web": 4 },
  "bySegment": { "default": 4 },
  "byStatus": { "BOT": 4 },
  "byVisitorType": { "human": 3, "agent": 1 },
  "topTools": [ { "name": "search_near_location", "calls": 3 } ],
  "byPage": [
    { "page": "/", "conversations": 2 },
    { "page": "/pages/associations-sante", "conversations": 1 }
  ],
  "topIntents": [
    { "question": "associations sportives près de Lyon", "count": 2 }
  ]
}
```

<Note>
  `byPage` (where engagement starts) and `topIntents` (what visitors actually ask)
  are the highest-signal fields. `toolCallsTotal` / `topTools` are computed from the
  persisted `tool_history`, **MCP calls included** — not a client-side heuristic.
</Note>

## GET /tenants/{slug}/conversations/export

Export the conversation list (one row per conversation) as **CSV** (default) or
**NDJSON**, for reporting.

**Required scope:** `conversations:read`

```bash theme={null}
curl "https://api.animam.ai/tenants/my-company/conversations/export?from=2024-01-19&format=csv" \
  -H "Authorization: Bearer ak_your_token" -o conversations.csv
```

### Query Parameters

| Param        | Type   | Description                                         |
| ------------ | ------ | --------------------------------------------------- |
| `from`, `to` | string | ISO window (default last 30 days, capped to 1 year) |
| `channel`    | string | Filter by channel                                   |
| `segment`    | string | Filter by segment slug                              |
| `format`     | string | `csv` (default) or `ndjson`                         |
| `limit`      | number | Max rows (default 1000, max 5000)                   |

### Response (CSV)

```csv theme={null}
id,created_at,updated_at,channel,status,visitor_type,segment,page_url,message_count,tool_calls_count,intent
conv_abc123,2024-01-25T10:30:00Z,2024-01-25T10:45:00Z,web,BOT,human,default,/pricing,8,2,"What are your prices?"
```

## GET /tenants/{slug}/conversations/stats/export

Export one aggregated dataset as **CSV** (default) or **NDJSON**.

**Required scope:** `stats:read`

```bash theme={null}
curl "https://api.animam.ai/tenants/my-company/conversations/stats/export?dataset=topIntents&format=csv" \
  -H "Authorization: Bearer ak_your_token" -o intents.csv
```

### Query Parameters

| Param                | Type   | Description                                                   |
| -------------------- | ------ | ------------------------------------------------------------- |
| `from`, `to`         | string | ISO window (default last 30 days, capped to 1 year)           |
| `granularity`        | string | `day` (default), `week`, `month` (for the `timeline` dataset) |
| `segment`, `channel` | string | Same filters as `/conversations/stats`                        |
| `dataset`            | string | `timeline` (default), `byPage`, `topIntents`, `topTools`      |
| `format`             | string | `csv` (default) or `ndjson`                                   |

### Response (CSV, `dataset=topIntents`)

```csv theme={null}
question,count
"associations sportives près de Lyon",2
"comment faire un don déductible",1
```