Builder API

Sessions

List chat sessions and retrieve messages from your Chipp app

| View as Markdown
1 min read
# api # builder-api # rest # sessions # messages # chat-logs # transcripts

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

List Sessions

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

Returns a paginated list of chat sessions, newest first.

Query Parameters

ParameterTypeDefaultDescription
limitinteger25Results per page (1-100)
cursorstring—Pagination cursor from previous response
sourcestring—Filter by channel
consumer_idUUID—Filter by consumer
started_afterISO 8601—Sessions started after this date
started_beforeISO 8601—Sessions started before this date
searchstring—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

plaintext
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

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

Returns the messages in a session, ordered chronologically.

Query Parameters

ParameterTypeDefaultDescription
limitinteger25Results per page (1-100)
cursorstring—Pagination cursor from previous response
rolestring—Filter by role: user, assistant, system, or tool
created_afterISO 8601—Messages created after this date
created_beforeISO 8601—Messages created before this date
includestring—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

FieldTypeDescription
idstringUnique message identifier
session_idUUIDThe session this message belongs to
rolestringuser, assistant, system, or tool
contentstringMessage text content
modelstring or nullLLM model used (null for user messages)
token_countinteger or nullToken count for this message
latency_msinteger or nullResponse latency in milliseconds
audio_urlstring or nullURL to audio recording, if applicable
audio_duration_msinteger or nullAudio duration in milliseconds
tagsarray of objectsTags applied to this message. Each object has id (UUID), name (string), and color (hex string)
feedbackobject or nullFeedback on this message, if any
created_atISO 8601When 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"