# Sessions

List chat sessions and retrieve messages from your Chipp app

---

Sessions represent individual chat conversations with your app. Each session contains messages exchanged between a consumer and your AI.

## List Sessions

```
GET /api/v1/apps/{appId}/sessions
```

Returns a paginated list of chat sessions, newest first.

### Query Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `limit` | integer | 25 | Results per page (1-100) |
| `cursor` | string | -- | Pagination cursor from previous response |
| `source` | string | -- | Filter by channel |
| `consumer_id` | UUID | -- | Filter by consumer |
| `started_after` | ISO 8601 | -- | Sessions started after this date |
| `started_before` | ISO 8601 | -- | Sessions started before this date |
| `search` | string | -- | Case-insensitive substring search on session titles (max 200 chars) |

**Source values:** `APP`, `API`, `WHATSAPP`, `SLACK`, `EMAIL`, `VOICE`, `WIDGET`, `ACP`

### Example

```bash
curl "https://build.chipp.ai/api/v1/apps/YOUR_APP_ID/sessions?limit=10&source=APP" \
  -H "Authorization: Bearer chipp_YOUR_API_KEY"
```

### Response

```json
{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "consumer_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "consumer": {
        "email": "jane@example.com",
        "name": "Jane Smith"
      },
      "title": "Help with onboarding",
      "source": "APP",
      "mode": "default",
      "is_bookmarked": false,
      "is_multiplayer": false,
      "message_count": 12,
      "started_at": "2025-06-15T14:30:00Z",
      "ended_at": "2025-06-15T14:45:00Z",
      "last_activity_at": "2025-06-15T14:45:00Z"
    }
  ],
  "pagination": {
    "has_more": true,
    "next_cursor": "eyJpZCI6IjU1MGU4NDAw...",
    "limit": 10
  }
}
```

### Filtering by Date Range

```bash
curl "https://build.chipp.ai/api/v1/apps/YOUR_APP_ID/sessions?started_after=2025-06-01T00:00:00Z&started_before=2025-06-30T23:59:59Z" \
  -H "Authorization: Bearer chipp_YOUR_API_KEY"
```

### Filtering by Consumer

```bash
curl "https://build.chipp.ai/api/v1/apps/YOUR_APP_ID/sessions?consumer_id=7c9e6679-7425-40de-944b-e07fc1f90ae7" \
  -H "Authorization: Bearer chipp_YOUR_API_KEY"
```

---

## Get Session

```
GET /api/v1/apps/{appId}/sessions/{sessionId}
```

Returns a single session by ID.

### Example

```bash
curl "https://build.chipp.ai/api/v1/apps/YOUR_APP_ID/sessions/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer chipp_YOUR_API_KEY"
```

### Response

```json
{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "consumer_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "consumer": {
      "email": "jane@example.com",
      "name": "Jane Smith"
    },
    "title": "Help with onboarding",
    "source": "APP",
    "mode": "default",
    "is_bookmarked": false,
    "is_multiplayer": false,
    "message_count": 12,
    "started_at": "2025-06-15T14:30:00Z",
    "ended_at": "2025-06-15T14:45:00Z",
    "last_activity_at": "2025-06-15T14:45:00Z"
  }
}
```

### Error: Session Not Found (404)

```json
{
  "error": {
    "code": "not_found",
    "message": "Session not found"
  }
}
```

---

## List Session Messages

```
GET /api/v1/apps/{appId}/sessions/{sessionId}/messages
```

Returns the messages in a session, ordered chronologically.

### Query Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `limit` | integer | 25 | Results per page (1-100) |
| `cursor` | string | -- | Pagination cursor from previous response |
| `role` | string | -- | Filter by role: `user`, `assistant`, `system`, or `tool` |
| `created_after` | ISO 8601 | -- | Messages created after this date |
| `created_before` | ISO 8601 | -- | Messages created before this date |
| `include` | string | -- | Comma-separated list of extra fields to include |

**Include values:**
- `tool_details` -- Adds `tool_calls` and `tool_results` fields to each message. These are arrays when the message invoked tools, or `null` when it did not

### Example

```bash
curl "https://build.chipp.ai/api/v1/apps/YOUR_APP_ID/sessions/550e8400-e29b-41d4-a716-446655440000/messages?limit=50" \
  -H "Authorization: Bearer chipp_YOUR_API_KEY"
```

### Response

```json
{
  "data": [
    {
      "id": "msg-001",
      "session_id": "550e8400-e29b-41d4-a716-446655440000",
      "role": "user",
      "content": "How do I get started with your platform?",
      "model": null,
      "token_count": 42,
      "latency_ms": null,
      "audio_url": null,
      "audio_duration_ms": null,
      "tags": [],
      "feedback": null,
      "created_at": "2025-06-15T14:30:00Z"
    },
    {
      "id": "msg-002",
      "session_id": "550e8400-e29b-41d4-a716-446655440000",
      "role": "assistant",
      "content": "Welcome! Here's how to get started...",
      "model": "gpt-4.1",
      "token_count": 150,
      "latency_ms": 1200,
      "audio_url": null,
      "audio_duration_ms": null,
      "tags": [{ "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "onboarding", "color": "#3b82f6" }],
      "feedback": null,
      "created_at": "2025-06-15T14:30:05Z"
    }
  ],
  "pagination": {
    "has_more": false,
    "next_cursor": null,
    "limit": 50
  }
}
```

### Response Fields

| Field | Type | Description |
|-------|------|-------------|
| `id` | string | Unique message identifier |
| `session_id` | UUID | The session this message belongs to |
| `role` | string | `user`, `assistant`, `system`, or `tool` |
| `content` | string | Message text content |
| `model` | string or null | LLM model used (null for user messages) |
| `token_count` | integer or null | Token count for this message |
| `latency_ms` | integer or null | Response latency in milliseconds |
| `audio_url` | string or null | URL to audio recording, if applicable |
| `audio_duration_ms` | integer or null | Audio duration in milliseconds |
| `tags` | array of objects | Tags applied to this message. Each object has `id` (UUID), `name` (string), and `color` (hex string) |
| `feedback` | object or null | Feedback on this message, if any |
| `created_at` | ISO 8601 | When the message was created |

### With Tool Details

```bash
curl "https://build.chipp.ai/api/v1/apps/YOUR_APP_ID/sessions/SESSION_ID/messages?include=tool_details" \
  -H "Authorization: Bearer chipp_YOUR_API_KEY"
```

```json
{
  "data": [
    {
      "id": "msg-003",
      "session_id": "550e8400-e29b-41d4-a716-446655440000",
      "role": "assistant",
      "content": "Let me look that up for you.",
      "model": "gpt-4.1",
      "token_count": 180,
      "latency_ms": 2400,
      "audio_url": null,
      "audio_duration_ms": null,
      "tags": [],
      "feedback": null,
      "created_at": "2025-06-15T14:31:00Z",
      "tool_calls": [
        {
          "tool_name": "search_knowledge",
          "status": "completed"
        }
      ],
      "tool_results": [
        {
          "tool_name": "search_knowledge",
          "result": "..."
        }
      ]
    }
  ],
  "pagination": {
    "has_more": false,
    "next_cursor": null,
    "limit": 25
  }
}
```

### Filtering by Role

To retrieve only user messages (useful for extracting questions/feedback):

```bash
curl "https://build.chipp.ai/api/v1/apps/YOUR_APP_ID/sessions/SESSION_ID/messages?role=user" \
  -H "Authorization: Bearer chipp_YOUR_API_KEY"
```