WebSocket API

Use the WebSocket API for real-time live chat integration. It provides instant message delivery, typing indicators, presence detection, auto-translation, and session management.

Endpoint

wss://webchatagent.com/api/livechat

The WebSocket API uses JSON messages for all communication.

Connection Roles

When connecting, you specify your role:

Role	Description
`user`	A website visitor participating in a chat
`admin`	A human agent managing live chat sessions
`widget`	The embedded chat widget on a website

Client Events (You Send)

`client:join`

Join a live chat session. This is the first event you must send after connecting.

{
  "type": "client:join",
  "chatbotId": "YOUR_CHATBOT_ID",
  "sessionId": "SESSION_ID",
  "as": "user",
  "lang": "en",
  "translateEnabled": true,
  "retranslateBacklog": false
}

Field	Type	Required	Description
`chatbotId`	string	Yes	Your chatbot's UUID.
`sessionId`	string	Yes	The chat session ID.
`as`	string	Yes	Connection role: `user`, `admin`, or `widget`.
`lang`	string	No	Preferred language code (e.g. `en`, `de`, `fr`).
`translateEnabled`	boolean	No	Enable auto-translation for this session.
`retranslateBacklog`	boolean	No	Translate existing messages when joining.

`client:message`

Send a message in the current session.

{
  "type": "client:message",
  "chatbotId": "YOUR_CHATBOT_ID",
  "sessionId": "SESSION_ID",
  "sender": "user",
  "content": "I need help with my order",
  "lang": "en"
}

Field	Type	Required	Description
`chatbotId`	string	Yes	Your chatbot's UUID.
`sessionId`	string	Yes	The chat session ID.
`sender`	string	Yes	Who is sending: `user` or `admin`.
`content`	string	Yes	The message text.
`lang`	string	No	Message language for translation.

`client:typing`

Send typing indicator.

{
  "type": "client:typing",
  "chatbotId": "YOUR_CHATBOT_ID",
  "sessionId": "SESSION_ID",
  "sender": "user",
  "isTyping": true
}

`client:meta`

Update session metadata (page information).

{
  "type": "client:meta",
  "chatbotId": "YOUR_CHATBOT_ID",
  "sessionId": "SESSION_ID",
  "pageUrl": "https://example.com/pricing",
  "pageTitle": "Pricing - Example",
  "referrer": "https://google.com",
  "browserLanguage": "en-US"
}

`client:agent_takeover`

Admin takes over a session from the bot.

{
  "type": "client:agent_takeover",
  "chatbotId": "YOUR_CHATBOT_ID",
  "sessionId": "SESSION_ID"
}

`client:end`

End a live chat session.

{
  "type": "client:end",
  "chatbotId": "YOUR_CHATBOT_ID",
  "sessionId": "SESSION_ID",
  "reason": "resolved"
}

`client:widget_open` / `client:widget_close`

Notify when the chat widget is opened or closed.

{
  "type": "client:widget_open",
  "chatbotId": "YOUR_CHATBOT_ID",
  "sessionId": "SESSION_ID",
  "pageUrl": "https://example.com",
  "pageTitle": "Home",
  "browserLanguage": "en-US"
}

Server Events (You Receive)

`livechat:status`

Session status update.

{
  "type": "livechat:status",
  "ok": true,
  "chatbotId": "YOUR_CHATBOT_ID",
  "sessionId": "SESSION_ID",
  "status": "open",
  "mode": "human",
  "userName": "John",
  "userEmail": "john@example.com",
  "userLanguage": "en"
}

Field	Type	Description
`status`	string	Session status: `waiting` (waiting for agent), `open` (agent connected), `closed`.
`mode`	string	Current mode: `bot` or `human`.
`userName`	string	Visitor's name (if collected via Leads).
`userEmail`	string	Visitor's email (if collected).
`userLanguage`	string	Detected visitor language.

`livechat:message`

New message in the session.

{
  "type": "livechat:message",
  "id": "msg_abc123",
  "sessionId": "SESSION_ID",
  "sender": "admin",
  "content": "Hello! How can I help you today?",
  "country": "DE",
  "createdAt": "2025-01-15T10:30:00Z",
  "file": null,
  "audience": null,
  "historical": false
}

Field	Type	Description
`id`	string	Unique message ID.
`sender`	string	Message sender: `user`, `admin`, or `assistant`.
`content`	string	Message text content.
`country`	string	Sender's country code (if detected).
`createdAt`	string	ISO 8601 timestamp.
`file`	object	Attached file information (if any).
`audience`	string	Message visibility scope (if restricted).
`historical`	boolean	Whether this is a backlog message sent on join.

`livechat:typing`

Typing indicator from another participant.

`livechat:presence`

Online/offline status of participants.

`livechat:meta`

Updated session metadata (current page, referrer, etc.).

`livechat:ended`

Session has been ended.

{
  "type": "livechat:ended",
  "sessionId": "SESSION_ID",
  "reason": "resolved"
}

`livechat:active_count` / `livechat:waiting_count`

Current count of active and waiting sessions (admin only).

`livechat:new_request`

Notification of a new live chat request (admin only).

`livechat:widget_sessions`

List of currently active widget sessions (admin only).

Auto-Translation

The WebSocket API supports automatic translation between visitor and agent languages:

Set translateEnabled: true when joining a session
Set lang to your preferred language
Messages from the other party are automatically translated using Gemini AI
Original and translated text are both available

This allows agents to communicate with visitors in any language without manual translation.

Example: Custom Live Chat Client

// Connect to WebSocket
const ws = new WebSocket('wss://webchatagent.com/api/livechat');

ws.onopen = () => {
  // Join a session as a user
  ws.send(JSON.stringify({
    type: 'client:join',
    chatbotId: 'YOUR_CHATBOT_ID',
    sessionId: 'SESSION_ID',
    as: 'user',
    lang: 'en'
  }));
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);

  switch (data.type) {
    case 'livechat:message':
      console.log(`${data.sender}: ${data.content}`);
      break;
    case 'livechat:typing':
      console.log('Agent is typing...');
      break;
    case 'livechat:status':
      console.log(`Session status: ${data.status}, mode: ${data.mode}`);
      break;
    case 'livechat:ended':
      console.log(`Session ended: ${data.reason}`);
      ws.close();
      break;
  }
};

// Send a message
function sendMessage(text) {
  ws.send(JSON.stringify({
    type: 'client:message',
    chatbotId: 'YOUR_CHATBOT_ID',
    sessionId: 'SESSION_ID',
    sender: 'user',
    content: text,
    lang: 'en'
  }));
}

// Send typing indicator
function sendTyping(isTyping) {
  ws.send(JSON.stringify({
    type: 'client:typing',
    chatbotId: 'YOUR_CHATBOT_ID',
    sessionId: 'SESSION_ID',
    sender: 'user',
    isTyping
  }));
}