Conversations API

The Conversations API provides access to all AI sales conversations captured by Synaptiq. Retrieve conversation lists, view full message histories, and filter by lead, status, or date range.

List Conversations

Retrieve a paginated list of conversations with optional filtering.

Query Parameters

| Parameter | Type | Required | Description | |-----------------|---------|----------|-------------------------------------------------------------------------| | page | integer | No | Page number. Default: 1. | | limit | integer | No | Results per page. Min: 1, Max: 100. Default: 25. | | leadId | string | No | Filter conversations belonging to a specific lead. | | status | string | No | Filter by status: active, closed, handed_off, expired. | | channel | string | No | Filter by channel: web_chat, api, whatsapp, slack. | | startDate | string | No | ISO 8601 date. Return conversations started on or after this date. | | endDate | string | No | ISO 8601 date. Return conversations started on or before this date. | | sortBy | string | No | Sort field: startedAt, lastMessageAt, messageCount. Default: lastMessageAt. | | sortOrder | string | No | Sort direction: asc or desc. Default: desc. |

Request

curl "https://synaptiqintel.com/api/v1/conversations?status=active&limit=5&sortBy=lastMessageAt" \
  -H "Authorization: Bearer sk_live_abc123def456ghi789jkl012mno345"

Response

{
  "data": [
    {
      "id": "conv_01HQ7ABC2DEF3GHI4JKL5MNO6P",
      "leadId": "lead_01HQ3VXK9BWMN4F6T2P8R5GYSC",
      "visitorId": "visitor_8f3a2b1c",
      "channel": "web_chat",
      "status": "active",
      "subject": "Pricing inquiry and demo request",
      "messageCount": 12,
      "summary": "Visitor inquired about Pro plan pricing, requested a live demo, and asked about CRM integrations. High purchase intent detected.",
      "intents": ["pricing_inquiry", "demo_request", "integration_question"],
      "leadScore": 87,
      "assignedTo": null,
      "startedAt": "2026-04-05T09:15:00.000Z",
      "lastMessageAt": "2026-04-05T11:42:00.000Z",
      "createdAt": "2026-04-05T09:15:00.000Z"
    },
    {
      "id": "conv_01HQ7QRS8TUV9WXY0ZAB1CDE2F",
      "leadId": "lead_01HQ6JKL8MWPN3D5R7S9T1UVWX",
      "visitorId": "visitor_2d4e6f8a",
      "channel": "web_chat",
      "status": "active",
      "subject": "Product comparison question",
      "messageCount": 6,
      "summary": "Visitor compared Synaptiq with a competitor. Asked about feature differences and onboarding timeline.",
      "intents": ["competitor_comparison", "onboarding_inquiry"],
      "leadScore": 64,
      "assignedTo": null,
      "startedAt": "2026-04-05T10:30:00.000Z",
      "lastMessageAt": "2026-04-05T10:48:00.000Z",
      "createdAt": "2026-04-05T10:30:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 5,
    "total": 142,
    "totalPages": 29,
    "hasMore": true
  }
}

Get a Conversation

Retrieve a single conversation with its full message history.

Query Parameters

| Parameter | Type | Required | Description | |------------------|---------|----------|----------------------------------------------------------------| | includeMessages| boolean | No | Include the full message array. Default: true. | | messageLimit | integer | No | Max messages to return. Default: 50. Max: 200. | | messageOffset | integer | No | Skip this many messages from the beginning. Default: 0. |

Request

curl "https://synaptiqintel.com/api/v1/conversations/conv_01HQ7ABC2DEF3GHI4JKL5MNO6P?messageLimit=10" \
  -H "Authorization: Bearer sk_live_abc123def456ghi789jkl012mno345"

Response

{
  "id": "conv_01HQ7ABC2DEF3GHI4JKL5MNO6P",
  "leadId": "lead_01HQ3VXK9BWMN4F6T2P8R5GYSC",
  "visitorId": "visitor_8f3a2b1c",
  "channel": "web_chat",
  "status": "active",
  "subject": "Pricing inquiry and demo request",
  "messageCount": 12,
  "summary": "Visitor inquired about Pro plan pricing, requested a live demo, and asked about CRM integrations. High purchase intent detected.",
  "intents": ["pricing_inquiry", "demo_request", "integration_question"],
  "leadScore": 87,
  "metadata": {
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
    "referrer": "https://www.google.com",
    "landingPage": "/pricing"
  },
  "messages": [
    {
      "id": "msg_01HQ7ABC000000000000000001",
      "role": "user",
      "content": "Hi, I'm looking at your pricing page. Can you explain the difference between Pro and Enterprise?",
      "createdAt": "2026-04-05T09:15:00.000Z"
    },
    {
      "id": "msg_01HQ7ABC000000000000000002",
      "role": "assistant",
      "content": "Hi there! Happy to help break that down for you.\n\n**Pro ($149/mo)** is designed for growing teams and includes up to 10,000 conversations per month, 5 AI agents, advanced analytics, and integrations with popular CRMs like Salesforce and HubSpot.\n\n**Enterprise** is our custom plan for large organizations. It includes unlimited conversations, dedicated account management, custom AI model training, SSO, and an SLA guarantee.\n\nWhat size is your team? That'll help me recommend the right fit.",
      "intent": "pricing_inquiry",
      "confidence": 0.96,
      "createdAt": "2026-04-05T09:15:02.000Z"
    },
    {
      "id": "msg_01HQ7ABC000000000000000003",
      "role": "user",
      "content": "We have about 50 sales reps. We're currently using Drift but looking to switch.",
      "createdAt": "2026-04-05T09:16:30.000Z"
    },
    {
      "id": "msg_01HQ7ABC000000000000000004",
      "role": "assistant",
      "content": "With 50 reps, the Enterprise plan would be the best fit. Many of our customers have migrated from Drift and typically see a 40% improvement in lead qualification accuracy.\n\nWould you like to schedule a personalized demo? I can connect you with our Enterprise team to discuss a custom package.",
      "intent": "competitor_comparison",
      "confidence": 0.91,
      "createdAt": "2026-04-05T09:16:33.000Z"
    }
  ],
  "startedAt": "2026-04-05T09:15:00.000Z",
  "lastMessageAt": "2026-04-05T11:42:00.000Z",
  "createdAt": "2026-04-05T09:15:00.000Z"
}

Filter by Lead

Retrieve all conversations for a specific lead by passing the leadId query parameter:

curl "https://synaptiqintel.com/api/v1/conversations?leadId=lead_01HQ3VXK9BWMN4F6T2P8R5GYSC" \
  -H "Authorization: Bearer sk_live_abc123def456ghi789jkl012mno345"

This returns all conversations associated with that lead across all channels and time periods.

Filter by Date Range

Use startDate and endDate to scope conversations to a specific window:

curl "https://synaptiqintel.com/api/v1/conversations?startDate=2026-04-01T00:00:00Z&endDate=2026-04-05T23:59:59Z&status=closed" \
  -H "Authorization: Bearer sk_live_abc123def456ghi789jkl012mno345"

Dates must be in ISO 8601 format. Both parameters are optional and can be used independently.

Conversation Statuses

| Status | Description | |--------------|----------------------------------------------------------------------| | active | The conversation is ongoing. New messages can be sent and received. | | closed | The conversation has been marked as complete. | | handed_off | The conversation was transferred to a human agent. | | expired | The session timed out after 30 minutes of inactivity. |

Response Fields Reference

| Field | Type | Description | |-----------------|----------|----------------------------------------------------------------| | id | string | Unique conversation identifier. | | leadId | string | The associated lead ID, if identified. | | visitorId | string | Anonymous visitor identifier. | | channel | string | The channel where the conversation took place. | | status | string | Current conversation status. | | subject | string | AI-generated subject summarizing the conversation topic. | | messageCount | integer | Total number of messages in the conversation. | | summary | string | AI-generated summary of the conversation. | | intents | string[] | Array of detected intents throughout the conversation. | | leadScore | integer | The lead score at the end of the conversation (0-100). | | assignedTo | string | User ID of the assigned agent, if handed off. | | messages | array | Array of message objects (when includeMessages is true). | | startedAt | string | ISO 8601 timestamp of the first message. | | lastMessageAt | string | ISO 8601 timestamp of the most recent message. | | createdAt | string | ISO 8601 timestamp of conversation creation. |

Error Responses

| Status Code | Error | Description | |-------------|----------------|------------------------------------------------| | 400 | invalid_request | Invalid query parameters or date format. | | 401 | unauthorized | Invalid or missing API key. | | 404 | not_found | Conversation with the given ID does not exist. |