Webchat widget

The webchat widget is a standalone script at client/public/webchat-widget.js.

Include required scripts

<script src="https://cdn.socket.io/4.5.4/socket.io.min.js"></script>
<script src="https://your-cdn.example.com/webchat-widget.js"></script>

Initialize widget

<script>
  window.TetherChat.init({
    webchatConfigId: 'YOUR_CONFIG_ID',
    apiUrl: 'https://your-api.example.com',
    name: 'Support assistant',
    starterMessage: 'Hi, how can we help?',
    primaryColor: '#0F766E',
  });
</script>

Runtime behavior

• Generates and persists a browser device ID.
• Opens socket connection on /socket/webchat.
• Handles realtime events like send_message_to_webchat and csat_request.
• Tracks delivery state per customer message: a bubble renders as Sending… until the platform acknowledges the message is stored, then as sent. Anything else shows Not sent · Tap to retry.
• Tracks unread message count and tab visibility for notifications.
• Supports mobile viewport handling, including Android keyboard behavior.

Delivery acknowledgment

A customer message is only marked sent after a stored-acknowledgment travels back from the API through the webchat socket server. The widget never marks a message sent on the strength of a local emit.

• Every send carries a widget-generated clientMessageId, scoped to the webchat session. Retries reuse it, and the API collapses a replay onto the row it already stored instead of creating a duplicate.
• Failed sends are retried automatically with backoff, replayed in order when the socket reconnects or a send gets through, and then swept every minute while the tab stays open. Non-retryable failures (chat ended, blocked) show the reason without a retry link.
• Headless integrations receive message_sent only after the acknowledgment, message_failed with { message, code, retryable } otherwise, and can call TetherChat.retry(clientMessageId). TetherChat.send(...) resolves to true once the message is stored.

Operational notes

• Ensure Socket.io CDN script loads before widget initialization.
• Keep widget host and API host CORS settings aligned.
• Validate CSP headers allow script and websocket connections.

For the service-side APIs behind the widget, see the Conversations guide.