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

# Chat

# Chat Analytics API

> **Route:** `POST /api/groups/chat`

Get analytics data for chat usage within a group, including message counts across different chat types and optional student-level breakdowns.

## Authentication

This endpoint requires authentication using an API key.

**Header Required:**

```
x-api-key: YOUR_API_KEY
```

## Parameters

### Query Parameters

| Parameter   | Type    | Required | Default                    | Description                                                                 |
| ----------- | ------- | -------- | -------------------------- | --------------------------------------------------------------------------- |
| `startDate` | string  | No       | `2025-01-01T00:00:00.000Z` | Start date for analytics period (ISO 8601 format)                           |
| `endDate`   | string  | No       | Current date               | End date for analytics period (ISO 8601 format)                             |
| `students`  | boolean | No       | `false`                    | Whether to return student-level data (`true`) or group-level data (`false`) |

## Response Format

### Group-Level Data (students=false)

Returns aggregated chat analytics for the entire group.

```json theme={null}
{
  "success": true,
  "reports": [
    {
      "startDate": "2025-01-01T00:00:00.000Z",
      "endDate": "2025-01-07T23:59:59.999Z",
      "numStudentsUsed": 25,
      "data": [
        {
          "title": "Total Messages",
          "value": 1250
        },
        {
          "title": "Tutor Me Messages",
          "value": 300
        },
        {
          "title": "Test Messages",
          "value": 200
        },
        {
          "title": "Flashcard Messages",
          "value": 180
        },
        {
          "title": "Material Messages",
          "value": 220
        },
        {
          "title": "Live Lecture Messages",
          "value": 150
        },
        {
          "title": "Main Chat Messages",
          "value": 200
        }
      ]
    }
  ]
}
```

### Student-Level Data (students=true)

Returns individual student chat analytics.

```json theme={null}
{
  "success": true,
  "reports": [
    {
      "startDate": "2025-01-01T00:00:00.000Z",
      "endDate": "2025-01-07T23:59:59.999Z",
      "studentName": "John Doe",
      "studentId": "user_123456",
      "data": [
        {
          "title": "Total Messages",
          "value": 45
        },
        {
          "title": "Tutor Me Messages",
          "value": 12
        },
        {
          "title": "Test Messages",
          "value": 8
        },
        {
          "title": "Flashcard Messages",
          "value": 7
        },
        {
          "title": "Material Messages",
          "value": 9
        },
        {
          "title": "Live Lecture Messages",
          "value": 5
        },
        {
          "title": "Main Chat Messages",
          "value": 4
        }
      ]
    }
  ]
}
```

## Data Fields Explained

### Message Types

* **Total Messages**: Sum of all chat messages sent by students
* **Tutor Me Messages**: Messages sent through the Tutor Me chat feature
* **Test Messages**: Messages related to test interactions
* **Flashcard Messages**: Messages sent during flashcard sessions
* **Material Messages**: Messages related to study materials
* **Live Lecture Messages**: Messages sent during live lecture sessions
* **Main Chat Messages**: General chat messages not categorized elsewhere

### Additional Fields

* **numStudentsUsed** (Group-level only): Number of unique students who sent messages
* **studentName** (Student-level only): Display name of the student
* **studentId** (Student-level only): Unique identifier for the student

## Error Responses

### 403 Unauthorized

Returned when API key is missing or invalid.

```json theme={null}
{
  "error": "Unauthorized"
}
```

**Causes:**

* Missing `x-api-key` header
* Invalid API key
* API key not associated with a valid group plan

### 400 Bad Request

Returned when required parameters are missing.

```json theme={null}
{
  "error": "Missing params"
}
```

## Notes

* Reports are automatically sorted by start date in ascending order
* Date ranges are inclusive of both start and end dates
* All timestamps should be in ISO 8601 format