​
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

ParameterTypeRequiredDefaultDescription
startDatestringNo2025-01-01T00:00:00.000ZStart date for analytics period (ISO 8601 format)
endDatestringNoCurrent dateEnd date for analytics period (ISO 8601 format)
studentsbooleanNofalseWhether 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.

{
  "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.

{
  "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.

{
  "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.

{
  "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