Sessions | Chipp Docs

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

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

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

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"

Log a Conversation

plaintext

POST /api/v1/apps/{appId}/conversations/log

Push a chat turn into the Conversations tab from an external pipeline (n8n, Zapier, Make.com, or a custom backend that handles the AI loop itself). The endpoint creates the session and consumer on first call, and reuses them by session_id or external_id on subsequent calls.

Requires sessions:write scope. The default key minted by the Alchemist already includes this; if you minted a key via the management endpoint, see the overview for how to request sessions:write explicitly.

Request Body

Field	Type	Required	Description
`messages`	array	yes	1–50 turns. Each item: `role` (`user` or `assistant`), `content` (1–100,000 chars), optional `model` (string, ≤255 chars).
`session_id`	UUID	no	Continue an existing session. Server validates the session belongs to this app.
`external_id`	string	no	Stable identifier to dedupe sessions across calls. First call creates a session bound to this id; subsequent calls with the same `external_id` append to it.
`channel`	string	no	One of `api` (default), `custom`, `whatsapp`, `sms`, `imessage`, `telegram`, `discord`, `teams`, `slack`, `email`. Drives the badge in the Conversations tab and the consumer resolution (named channels prefix the identifier with the channel name; `api` / `custom` resolve to an anonymous-style consumer).
`consumer`	object	no	`{ channel_user_id?, email?, name? }`. For named channels, `channel_user_id` is the platform identifier (phone number for WhatsApp/SMS, Slack user id, etc.). For `api`/`custom`, omit and a fresh anonymous consumer is created per `external_id`.
`title`	string	no	Session title (1–255 chars). Only applied when creating a new session.
`notify_subscribers`	boolean	no	Default `true`. When false, suppresses the per-app chat notification email for this turn.
`detect_tags`	boolean	no	Default `true`. When false, skips tag detection for this turn. Always skipped for ZDR (Zero Data Retention) apps regardless of this flag.
`client_request_id`	string	no	Idempotency key. Repeating the call with the same `client_request_id` within 10 minutes returns the cached result without re-inserting messages. Use this from n8n / Zapier where retries on transient failures are automatic.

Example: WhatsApp Bridge

bash

curl -X POST "https://build.chipp.ai/api/v1/apps/YOUR_APP_ID/conversations/log" \
  -H "Authorization: Bearer chipp_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp",
    "external_id": "wa-thread-+15551234567",
    "consumer": {
      "channel_user_id": "+15551234567",
      "name": "Jane Smith"
    },
    "messages": [
      { "role": "user", "content": "Hi, what are your hours?" },
      { "role": "assistant", "content": "We are open 9-5 EST.", "model": "gpt-4.1" }
    ],
    "client_request_id": "n8n-execution-abc123"
  }'

Example: Continuing a Session

bash

curl -X POST "https://build.chipp.ai/api/v1/apps/YOUR_APP_ID/conversations/log" \
  -H "Authorization: Bearer chipp_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "550e8400-e29b-41d4-a716-446655440000",
    "messages": [
      { "role": "user", "content": "Can you also tell me your address?" },
      { "role": "assistant", "content": "We are at 123 Main St.", "model": "gpt-4.1" }
    ]
  }'

Response (200)

json

{
  "data": {
    "session_id": "550e8400-e29b-41d4-a716-446655440000",
    "consumer_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "source": "WHATSAPP",
    "is_new_session": true,
    "messages": [
      {
        "id": "msg-001",
        "role": "user",
        "created_at": "2025-06-15T14:30:00Z"
      },
      {
        "id": "msg-002",
        "role": "assistant",
        "created_at": "2025-06-15T14:30:01Z"
      }
    ]
  }
}

Errors

Status	Code	When
400	`validation_error`	Body fails validation (missing required field, oversized message, unknown channel).
403	`insufficient_scope`	API key lacks `sessions:write`.
403	`forbidden`	`session_id` belongs to a different app.
404	`not_found`	`session_id` references a deleted session or doesn’t exist.
503	—	Transient database issue. Safe to retry (the Cloudflare Worker retries automatically up to 4 times).

Idempotency Guarantee

When client_request_id is provided, the endpoint caches the response for 10 minutes. Replaying the same client_request_id returns the cached session_id + messages array WITHOUT creating duplicate rows. This makes the endpoint safe for at-least-once delivery semantics (n8n / Zapier retries, Make.com retry policies, your own backoff loop).

Encrypted / ZDR Apps

For apps with org-level Zero Data Retention enabled, messages go to ephemeral Redis storage (4-hour TTL) instead of the database. Tag detection is automatically skipped. The session still appears in the Conversations tab while messages are in the TTL window.