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.