API reference

The widget talks to the ForeverChat gateway over a small HTTP + WebSocket API. You rarely need this directly — the snippet handles it — but here’s the surface for custom integrations.

Base URL. In this environment the gateway is https://gateway-381807041351.us-east4.run.app. All /v1/* routes send permissive CORS and return JSON errors as { "error": string }.

Endpoints

Method	Path	Description
POST	/v1/boot	Start/resume a visitor session; returns config, history, and status.
WS	/v1/ws	Visitor socket. Send messages, typing, read; receive agent replies.
WS	/v1/agent-ws	Agent socket (session token). Reply, note, assign, set status.
POST	/v1/upload	Upload a file (raw body). Returns an attachment record.
GET	/v1/files/:id	Stream a stored file from its unguessable capability URL.
POST	/v1/prechat	Submit the pre-chat form fields for a visitor.
POST	/v1/offline	Submit the offline form; creates a conversation and notifies.
GET	/v1/presence	Agent snapshot of live visitors for the monitoring page.

Boot a session

The widget calls POST /v1/boot on load with your app ID and (if it has one) a stored visitor token.

Request

curl -X POST https://gateway-381807041351.us-east4.run.app/v1/boot \
  -H 'Content-Type: application/json' \
  -d '{
    "appId": "fc_YOUR_APP_ID",
    "token": null,
    "page": { "url": "https://example.com/pricing", "title": "Pricing" }
  }'

Response (BootResponse)

{
  "token": "visitor-session-token",
  "config": { "color": "#4f46e5", "companyName": "Acme", "...": "..." },
  "messages": [ /* recent history within your plan's retention */ ],
  "agentOnline": true,
  "withinBusinessHours": true,
  "preChatDone": false
}

The visitor socket

After boot, connect to the visitor WebSocket with your app ID and the returned token. Messages are JSON events; the server acks each send and broadcasts agent replies back.

WebSocket

// Visitor socket
const ws = new WebSocket(
  "wss://gateway-381807041351.us-east4.run.app/v1/ws?appId=fc_YOUR_APP_ID&token=VISITOR_TOKEN"
);
ws.send(JSON.stringify({ type: "message", body: "Hi!", clientId: "c1" }));

Message bodies are plain text. ForeverChat never renders message content as HTML. Send and expect plain text — this is a deliberate XSS safeguard.

For identifying users on boot, see the Identity & HMAC guide.