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"
  }
}