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 X-Session-Id (client-generated UUID) and X-Company (from Settings → Company in the Freeday platform) headers.

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