Chat API

The Chat API powers Synaptiq's AI sales conversations. Use it to send visitor messages to the AI agent, receive intelligent responses, and manage chat sessions programmatically.

Send a Message

Send a message to the Synaptiq AI agent and receive a response. The agent uses your configured knowledge base, product catalog, and sales playbook to generate contextually relevant replies.

Request Body

Parameter	Type	Required	Description
message	string	Yes	The visitor's message text. Max 4,000 characters.
visitorId	string	Yes	A unique identifier for the visitor. Used to maintain conversation context.
sessionId	string	No	An existing session ID to continue a conversation. Omit to start a new one.
stream	boolean	No	Set to true for Server-Sent Events streaming. Default: false.
metadata	object	No	Arbitrary key-value pairs attached to the message for tracking.
language	string	No	ISO 639-1 language code for the response. Default: auto-detected.

Non-Streaming Request

curl -X POST https://synaptiqintel.com/api/v1/chat \
  -H "Authorization: Bearer sk_live_abc123def456ghi789jkl012mno345" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What pricing plans do you offer?",
    "visitorId": "visitor_8f3a2b1c",
    "metadata": {
      "page": "/pricing",
      "referrer": "google"
    }
  }'

Non-Streaming Response

{
  "id": "msg_01HQ3VXK9BWMN4F6T2P8R5GYSA",
  "sessionId": "sess_01HQ3VXK9BWMN4F6T2P8R5GYSB",
  "visitorId": "visitor_8f3a2b1c",
  "role": "assistant",
  "content": "Great question! We offer three plans designed to scale with your business:\n\n**Starter** — $49/mo: Up to 1,000 conversations, 1 AI agent, basic analytics.\n\n**Pro** — $149/mo: Up to 10,000 conversations, 5 AI agents, advanced analytics, CRM integrations.\n\n**Enterprise** — Custom pricing: Unlimited conversations, dedicated support, custom model training.\n\nWould you like me to help you figure out which plan is the best fit for your team?",
  "intent": "pricing_inquiry",
  "confidence": 0.94,
  "suggestedActions": [
    {
      "type": "link",
      "label": "View pricing page",
      "url": "/pricing"
    },
    {
      "type": "reply",
      "label": "Tell me about Pro",
      "message": "Tell me more about the Pro plan"
    }
  ],
  "leadScore": 72,
  "createdAt": "2026-04-05T14:32:18.000Z"
}

Response Fields

Field	Type	Description
id	string	Unique message identifier.
sessionId	string	The session this message belongs to. Reuse to continue the chat.
visitorId	string	The visitor identifier from the request.
role	string	Always "assistant" for AI responses.
content	string	The AI-generated response text in Markdown format.
intent	string	The detected intent of the visitor's message.
confidence	number	Confidence score for the detected intent (0.0 to 1.0).
suggestedActions	array	Suggested follow-up actions for the visitor.
leadScore	integer	Updated lead score based on the conversation so far (0-100).
createdAt	string	ISO 8601 timestamp of when the response was generated.

Streaming Responses

For real-time chat interfaces, use streaming mode. The response is delivered as Server-Sent Events (SSE).

curl -X POST https://synaptiqintel.com/api/v1/chat \
  -H "Authorization: Bearer sk_live_abc123def456ghi789jkl012mno345" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "message": "How does your AI handle objections?",
    "visitorId": "visitor_8f3a2b1c",
    "sessionId": "sess_01HQ3VXK9BWMN4F6T2P8R5GYSB",
    "stream": true
  }'

SSE Event Format

event: message_start
data: {"id":"msg_01HQ4ABC...","sessionId":"sess_01HQ3VXK..."}

event: content_delta
data: {"delta":"Our AI agent is trained to "}

event: content_delta
data: {"delta":"recognize common sales objections "}

event: content_delta
data: {"delta":"and respond with proven rebuttal frameworks."}

event: message_end
data: {"intent":"product_inquiry","confidence":0.89,"leadScore":75}

SSE Event Types

Event	Description
message_start	Sent once at the beginning. Contains id and sessionId.
content_delta	Sent multiple times. Each event contains a delta text chunk.
message_end	Sent once at the end. Contains metadata like intent and score.
error	Sent if an error occurs during generation.

Session Management

Sessions group messages into a single conversation thread. A session is automatically created when you send a message without a sessionId.

To continue an existing conversation, include the sessionId from a previous response:

curl -X POST https://synaptiqintel.com/api/v1/chat \
  -H "Authorization: Bearer sk_live_abc123def456ghi789jkl012mno345" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Can I get a demo of the Pro plan?",
    "visitorId": "visitor_8f3a2b1c",
    "sessionId": "sess_01HQ3VXK9BWMN4F6T2P8R5GYSB"
  }'

Session Behavior

• Sessions expire after 30 minutes of inactivity.
• A new session is created automatically when an expired sessionId is provided.
• Each session maintains full conversation context, enabling multi-turn dialogue.
• Sessions are automatically linked to leads when a visitor is identified.

Retrieve Session History

Retrieve the complete message history for a session.

curl https://synaptiqintel.com/api/v1/chat/sessions/sess_01HQ3VXK9BWMN4F6T2P8R5GYSB \
  -H "Authorization: Bearer sk_live_abc123def456ghi789jkl012mno345"

{
  "sessionId": "sess_01HQ3VXK9BWMN4F6T2P8R5GYSB",
  "visitorId": "visitor_8f3a2b1c",
  "leadId": "lead_01HQ3VXK9BWMN4F6T2P8R5GYSC",
  "status": "active",
  "messages": [
    {
      "id": "msg_01HQ3VXK9BWMN4F6T2P8R5GYSA",
      "role": "user",
      "content": "What pricing plans do you offer?",
      "createdAt": "2026-04-05T14:32:17.000Z"
    },
    {
      "id": "msg_01HQ3VXK9BWMN4F6T2P8R5GYSB",
      "role": "assistant",
      "content": "Great question! We offer three plans...",
      "intent": "pricing_inquiry",
      "createdAt": "2026-04-05T14:32:18.000Z"
    }
  ],
  "startedAt": "2026-04-05T14:32:17.000Z",
  "lastActivityAt": "2026-04-05T14:32:18.000Z"
}

Handoff to Human Agent

When the AI determines a conversation requires human attention (or a visitor explicitly requests it), the response includes a handoff object:

{
  "id": "msg_01HQ5DEF...",
  "role": "assistant",
  "content": "I'd love to connect you with one of our sales specialists who can walk you through a custom Enterprise proposal. Let me transfer you now.",
  "handoff": {
    "reason": "enterprise_inquiry",
    "priority": "high",
    "suggestedTeam": "enterprise-sales"
  }
}

Use the handoff object to trigger routing in your support platform or notify the appropriate team.

Error Responses

Status Code	Error	Description
400	invalid_request	Missing required fields or invalid message format.
401	unauthorized	Invalid or missing API key.
429	rate_limit_exceeded	Too many requests. See rate limit headers.
500	internal_error	An unexpected error occurred. Retry with backoff.

{
  "error": {
    "code": "invalid_request",
    "message": "The 'message' field is required and must be a non-empty string.",
    "doc_url": "https://synaptiqintel.com/docs/api-reference/chat-api"
  }
}