Freeday Webchat Realtime API 1.0.0

Real-time messaging API for the Freeday webchat, powered by Centrifugo. REST endpoints and the conversation data export are documented alongside this protocol on docs.freeday.ai.

Quick Start

All REST calls require the X-Company header (from Settings → Company in the Freeday platform). After the first call, they also require the X-Session-Id header.

The server issues the session ID. Do not generate one yourself. Send the first call without X-Session-Id, store the X-Session-Id header from its response, and send that ID on every later call. A session expires after 30 days without activity. A call with an expired or unknown session ID gets 403 with error code session_invalid. Then delete the stored session ID and conversation ID, and create a new conversation without X-Session-Id to get a new session. The new session cannot use the conversations of the expired one.

1. Create a conversation
2. Get a connection token
3. Connect — Open a WebSocket to wss://realtime.freeday.ai/connection/websocket with the token. See Centrifugo client SDK docs.
4. Get a subscription token
5. Subscribe — Subscribe to the channel from step 4 with a getToken callback.

Example (centrifuge-js):

const sub = client.newSubscription(channel, {
  getToken: async () => {
    const res = await fetch("https://api.freeday.ai/sdk/v1/auth/subscribe-token", {
      method: "POST",
      headers: { "Content-Type": "application/json", "X-Session-Id": sessionId, "X-Company": companyId },
      body: JSON.stringify({ conversation_id: conversationId }),
    });
    return (await res.json()).subscription_token;
  },
});
sub.on("publication", (ctx) => handleEnvelope(ctx.data));
sub.subscribe();

Message Flow

Sending: Publish a SendMessage via subscription.publish().

Receiving: The server streams MessageEnvelope objects. Envelopes carry a sequence number — discard out-of-order envelopes. Ignore envelopes with an unrecognized proto version.

Streaming example:

1. { operation: "replace", sequence: 1, message_snapshot: { status: "partial", blocks: [{ id: "b1", type: "typing", typing: true }] } }
2. { operation: "replace", sequence: 2, message_snapshot: { status: "partial", blocks: [{ id: "b2", type: "markdown", content: "Hello! I can" }] } }
3. { operation: "complete", sequence: 3, message_snapshot: { status: "complete", blocks: [{ id: "b2", type: "markdown", content: "Hello! I can help you with that." }] } }