# 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, most recent activity 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 and on the consumer's name, email, and identifier (max 200 chars) | **Source values:** `APP`, `API`, `MCP`, `WHATSAPP`, `SLACK`, `EMAIL`, `VOICE`, `WIDGET`, `ACP`, `DESKTOP`, `BUILDER` ### 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": "ai", "is_bookmarked": false, "is_multiplayer": false, "external_id": "patient-abc123", "query_params": [ { "name": "rp_token", "value": "abc123" }, { "name": "ab_variant", "value": "B" } ], "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 } } ``` ### Response Fields | Field | Type | Description | |-------|------|-------------| | `id` | UUID | Session identifier | | `consumer_id` | UUID or null | Consumer who opened this session | | `consumer` | object or null | `{ email, name }` for the consumer | | `title` | string or null | Session title (auto-generated or set by the builder) | | `source` | string | Channel: `APP`, `WHATSAPP`, `SLACK`, `EMAIL`, `VOICE`, `WIDGET`, `API`, etc. | | `mode` | string | Current session mode: `ai`, `human`, or `hybrid` | | `is_bookmarked` | boolean | Whether the session is bookmarked in the Conversations tab | | `is_multiplayer` | boolean | Whether this is a group chat session | | `external_id` | string or null | The value passed via `?chipp_external_id=` in the share URL (for web sessions), or the channel-namespaced key for channel sessions (e.g. `whatsapp:+15551234567`). Null when not set. Use this for deterministic attribution without model involvement. | | `query_params` | array | URL query parameters captured when the consumer opened the session, as `[{ name, value }]` objects. Empty array when none were present. Excludes Chipp control params (`bt`, `session`, `share`). Use for A/B variant, referral token, and campaign attribution. | | `message_count` | integer | Total messages in this session | | `started_at` | ISO 8601 | When the session was created | | `ended_at` | ISO 8601 or null | When the session ended, if known | | `last_activity_at` | ISO 8601 or null | Timestamp of last message or activity | ### 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": "ai", "is_bookmarked": false, "is_multiplayer": false, "external_id": "patient-abc123", "query_params": [ { "name": "rp_token", "value": "abc123" }, { "name": "ab_variant", "value": "B" } ], "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. If your organization has Zero Data Retention enabled, `data` is always an empty array. ### 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. For end-to-end encrypted sessions this is the placeholder `[Encrypted - only visible to the consumer]` | | `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` | integer or null | The rating on this message (`1` or `-1`), 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 ``` 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](/docs/builder-api/overview#requesting-write-scopes) 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 | (none) | Body fails schema validation (missing required field, oversized message, unknown channel). The body is `{ "error": "" }`, with no `code`. | | 400 | `validation_error` | The server rejected an otherwise well-formed request. | | 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. --- ## Conversation Export and Attribution ### Self-attributing transcripts Every session in the Builder API carries two attribution fields that let you tie a transcript back to the referral token, A/B arm, or patient identifier that the consumer arrived with -- with zero custom plumbing. | Field | What it holds | |-------|---------------| | `external_id` | The value passed via `?chipp_external_id=` in the share URL (or a channel-namespaced key like `whatsapp:+15551234567` for channel sessions). `null` when not set. | | `query_params` | Every other URL query param captured at session creation, as `[{ name, value }]`. Excludes Chipp control params (`bt`, `session`, `share`). Empty array when none were present. | **Example:** A link like `https://app.chipp.ai/chat/my-app?rp_token=abc123&ab_variant=B` produces: ```json { "external_id": null, "query_params": [ { "name": "rp_token", "value": "abc123" }, { "name": "ab_variant", "value": "B" } ] } ``` Because these fields are set at session creation and never change, you can join `query_params` to your patient/user records offline without a real-time side-channel. The `rp_token` in the transcript IS the attribution token -- no `session_id -> rp_token` mapping table required. ### Detecting completion with tool markers When you fetch messages from the org-wide export API (see below) with `?include=tool_details`, each message gains a `tools` array of compact markers that summarize tool and component invocations without the heavy code blobs. (The Builder API's `include=tool_details` returns the raw `tool_calls` and `tool_results` instead.) Detect that a consumer reached the natural wrap-up screen: ```javascript const completed = messages.some( m => m.tools?.some(t => t.name === "render_completion_screen") ); ``` Each marker shape: `{ id?, name?, type?, component?, success? }`. ### Scripted / cron pull (org-wide API) The Builder API (`chipp_` keys) covers a single app. For pulling data across all apps on a schedule, use the **org-wide export API** (`chipp_org_*` keys) -- it exposes the same `external_id`, `query_params`, and `tools` fields over HTTP and is designed for warehouse sync and cron jobs. See the [Org Export API guide](/docs/api/org-export) for authentication, endpoint reference, and a Snowflake sync recipe.