API Integration

Authentication model

Each API integration account has a unique integration token generated in your workspace.

• Pass integrationToken as a query parameter on /conversation endpoints.
• Treat the integration token like a secret and keep it server-side when possible.
• If allowedDomains are configured, browser requests from other domains are rejected.
• You can rotate the integration by creating a new account and retiring the old one.

Conversation model

conversationId is your customer/session key and should be stable per user when continuity is needed.

• Reuse the same conversationId to continue a thread and preserve full history.
• Omit conversationId on first message to start a fresh conversation id.
• Use your own user/customer ID as conversationId for deterministic mapping.
• History and message polling rely on conversationId and afterId cursor.

History payload shape

The history endpoint returns a normalized feed suitable for polling-based chat UIs and API clients.

• messages[] contains id, actor, type, body, data, createdAt.
• lastMessageId is a cursor you can pass back via afterId.
• limit defaults safely and is capped server-side.
• Internal activity records are filtered out by the backend.

{
  "conversationId": "customer-42",
  "messages": [
    {
      "id": "a12f...",
      "actor": "customer",
      "type": "message",
      "body": "Hey, can I reschedule?",
      "createdAt": "2026-02-09T20:05:13.021Z"
    }
  ],
  "lastMessageId": "a12f..."
}

Create integration and copy token

• Open Dashboard → Integrations and create an API integration.
• Copy the generated integration token from the account settings.
• Decide whether you want strict domain allowlisting for browser requests.
• Assign a Responder assistant to the API account (required for generated replies).
• Choose response mode: Auto replies or Manual approval (approved customers only).

Send a message via SSE

• Call /conversation/sse with integrationToken and textContent.
• Optionally pass conversationId to continue an existing customer thread.
• Use query parameters (EventSource). Do not send JSON body to this endpoint.
• Read streamed events and store the returned conversationId/userMessageId.

const params = new URLSearchParams({
  integrationToken: 'YOUR_INTEGRATION_TOKEN',
  textContent: 'Hi, can you help me with billing?',
  conversationId: 'customer-42'
});

const source = new EventSource(
  'https://api.your-domain.com/conversation/sse?' + params.toString()
);

source.onmessage = (event) => {
  const payload = JSON.parse(event.data);
  console.log(payload);
};

Poll history for updates and manual replies

• Call /conversation/history with integrationToken and conversationId.
• Store lastMessageId and pass it as afterId for incremental polling.
• Poll every 10-15 seconds (12 seconds is a practical default).

const query = new URLSearchParams({
  integrationToken: 'YOUR_INTEGRATION_TOKEN',
  conversationId: 'customer-42',
  afterId: 'LAST_MESSAGE_ID',
  limit: '100'
});

const res = await fetch('https://api.your-domain.com/conversation/history?' + query.toString());
const history = await res.json();