GTS WebChat docsby GTS Team

WebChat › Docs › Features

Features

Source: docs/features.md · USER DEV

This document captures the current WebChat app surface so product, GUI, relay, CLI, and deployment behavior stay aligned.

For a short user/AI overview, use:

docs/high-level-features.md

For the compact API reference, use:

docs/api-for-ai-and-devs.md

Core Identity

  • Email-only WebChat users.
  • One stable chat_address per email user.
  • Display name shown in directory, chats, CLI, and presence.
  • Local browser remembers email sessions on the current computer.
  • Relay DB stores users in pchat_users and sessions in pchat_sessions.
  • Sessions include:
  • device_name
  • session_name
  • listen_channel
  • last_seen_at
  • Duplicate sessions for the same user/device/session are replaced.
  • Expired sessions are cleaned.
  • Browser/CLI sends offline presence on close or stop.

GUI

  • Single-page WebChat GUI at web/app/webchat/chat.html.
  • Sidebar conversation list.
  • Relay Directory opens by default.
  • Search conversations.
  • Channel filters: All, SMS, WA, TG, Email, Notify, WebChat.
  • Local archive filter for conversations archived on this computer.
  • Local video filter for video-call conversations.
  • New conversation button.
  • Group creation button.
  • Contact import button.
  • Contact import supports CSV, XLSX, VCF, pasted rows, phone-native contact import, latest uploaded contact sync, QR import, template CSV download, and local CSV export.
  • Login/session switch button.
  • Settings modal with compact basic fields and advanced relay options.
  • Blocked users modal.
  • Local call history modal.
  • Saved messages / send-to-self entry point.
  • Message context menu:
  • copy
  • reply
  • translate
  • speak
  • edit
  • delete
  • archive conversation
  • block user
  • Modal close behavior:
  • close button
  • backdrop click
  • Escape key

Relay Directory

  • Shows visible public users.
  • Shows public groups and groups where current user is a member.
  • Shows online/offline state for users.
  • Users can hide from presence.
  • Users can click another user to start a direct WebChat conversation.
  • Directory refresh button.
  • Typing state is carried through the presence heartbeat.
  • Locally blocked users are marked in online lists.

Messaging

  • WebChat direct messages.
  • WebChat group messages.
  • Reply metadata support.
  • Message edit support.
  • Message delete support.
  • Read receipt support.
  • Delivery/read status display.
  • E2E key exchange scaffolding for direct WebChat conversations.
  • Browser notifications for background messages.
  • Typing indicator for active direct conversations.
  • Local conversation archive/unarchive.
  • Local chat export.
  • Local block list.
  • Relay abuse report endpoint with auto-block threshold support.

Groups

  • Public groups:
  • visible in relay directory
  • non-members can request to join
  • owner/admin must accept before user becomes a member
  • Private groups:
  • visible only to members
  • users must be invited/added
  • Group owner is automatically added as owner member.
  • Group members can add users by chat address.
  • Group header has a members view showing each member, the creator/admin tag, and the current user tag.
  • Group owner/admin can remove members from the members view.
  • Group mode can be chat or stream:
  • chat: all members can write
  • stream: creator is the writer, all other members are observers/read-only
  • stream write restrictions are enforced by the relay and mirrored in the GUI composer
  • Group owners see pending join request count.
  • Group owners can accept or reject join requests from the group header.
  • Group addresses use:
group:grp_...

Language

There is one language selector in the composer:

Auto / EN / ES / FR / DE / PT / RU / HI / HE / AR / ZH / JA / KO

Behavior:

  • Auto
  • outgoing text sends as typed
  • incoming text shows as sent
  • input direction auto-detects
  • selected language
  • outgoing text translates before sending
  • incoming text translates on receive
  • incoming voice transcript/caption translates on receiver side
  • outgoing voice stays as original audio
  • input direction and speech playback use selected language
  • floating keyboard button opens quick typing keys for the selected language

Important product rule:

  • Sender decides only their outgoing text language.
  • Receiver decides how incoming text and voice are translated.
  • Original voice clips are preserved.

Floating keyboard:

  • Click the keyboard icon beside the emoji button.
  • Select HE, AR, RU, HI, ES, FR, DE, or PT to show matching language keys.
  • Hebrew and Arabic use right-to-left keyboard layouts.
  • Chinese, Japanese, and Korean show punctuation helpers; full CJK typing should use the operating system IME.

Voice

  • Browser audio recording.
  • Native bridge hook for mobile/native audio recording.
  • Voice message upload through WebChat file upload endpoint.
  • Voice clips render with audio controls/waveform.
  • Manual transcribe action can put transcript into the composer.
  • Receiver-side voice flow:
incoming voice clip -> transcribe if needed -> translate to selected language -> show caption -> optional text-to-speech
  • Text-to-speech uses browser speechSynthesis.
  • Browser speech-to-text/dictation uses Web Speech API where available.

Files, Images, Video, Audio

  • Multiple file selection.
  • Parallel upload.
  • Image preview inline.
  • Video player inline.
  • Audio player inline.
  • Other files render as download/open links.
  • CLI can send files, video, audio, and voice attachments.
  • Uploaded files are stored under relay PCHAT_UPLOAD_DIR.
  • Relay serves uploaded files through GET /api/v1/webchat/files/<file_id>.

Video Calls

  • 1:1 WebChat video-call button.
  • WebRTC camera/microphone call.
  • Relay signaling endpoint:
/api/v1/webchat/call/signal
  • Supports offer, answer, ICE, hangup, reject, busy.
  • Mute button.
  • Camera on/off button.
  • Hang up button.
  • Local call history.
  • Group video calls are not implemented yet.
  • CLI/AI listener cannot join WebRTC calls.

Private Relay

  • Default mode can use public relay.
  • Users can run their own relay server.
  • GUI Settings -> Advanced -> Private Server Relay.
  • Users set custom Relay Server URL.
  • GUI can scan/import private relay settings from QR.
  • Relay exposes admin API endpoints for clients, phones, limits, metrics, audit, reports, and abuse controls. A full owner dashboard is not implemented yet.
  • App behavior remains the same:
  • login
  • directory
  • groups
  • join requests
  • files
  • voice
  • translation
  • CLI
  • Private relay docs:
docs/private-relay.md

CLI

CLI script:

scripts/webchat_cli.py

Capabilities:

  • create/reuse persona
  • fixed chat address
  • named computer/session metadata
  • generate GUI auto-login URL
  • list personas
  • send direct message
  • send group message
  • send file/video/audio/voice attachment
  • poll inbox once
  • watch inbox continuously
  • mark CLI presence online while watching
  • send offline presence on stop
  • connect to public or private relay

Inbound Callbacks And Phone Bridge

  • Relay supports inbound callback subscriptions:
  • GET|POST /api/v1/webchat/callbacks/inbound
  • DELETE /api/v1/webchat/callbacks/inbound/<callback_id>
  • Callback filters include channel, event type, source/contact, keyword, and call duration ranges.
  • Relay has callback job retry workers.
  • GUI has phone bridge settings and status polling for phone connectivity.
  • Native bridge hooks exist for QR scan, contacts import, and voice recording.

Private relay launch-link helper:

scripts/private_relay_link.py

Relay Endpoints

Key WebChat endpoints:

  • POST /api/v1/pchat/auth/request-code
  • POST /api/v1/pchat/auth/verify-code
  • GET /api/v1/pchat/auth/me
  • PUT /api/v1/pchat/auth/me
  • POST /api/v1/pchat/auth/logout
  • GET /api/v1/webchat/directory
  • POST /api/v1/webchat/presence
  • GET|POST /api/v1/webchat/groups
  • GET|POST /api/v1/webchat/groups/<group_id>/members
  • DELETE /api/v1/webchat/groups/<group_id>/members/<member_address>
  • GET|POST /api/v1/webchat/groups/<group_id>/join-requests
  • POST /api/v1/webchat/groups/<group_id>/join-requests/<request_id>
  • POST /api/v1/messages
  • POST /api/v1/webchat/poll
  • POST /api/v1/webchat/read
  • POST /api/v1/webchat/receipt-status
  • POST /api/v1/webchat/edit
  • POST /api/v1/webchat/delete
  • POST /api/v1/webchat/upload
  • GET /api/v1/webchat/files/<file_id>
  • POST /api/v1/webchat/transcribe
  • POST /api/v1/webchat/translate-text
  • GET|PUT /api/v1/webchat/language-prefs
  • POST /api/v1/webchat/call/signal
  • GET|POST /api/v1/webchat/callbacks/inbound
  • DELETE /api/v1/webchat/callbacks/inbound/<callback_id>
  • POST /api/v1/webchat/report

Deployment Files

  • start_web.sh: serves GUI.
  • start_relay.sh: starts relay.
  • Local start scripts auto-select a nearby free port when the requested port is busy; set WEBCHAT_STRICT_PORT=1 to fail on collision.
  • relay/.env.example: private relay config template.
  • relay/Dockerfile: containerized relay.
  • docker-compose.private-relay.yml: private relay compose file.
  • docs/private-relay.md: server setup guide.
  • docs/ai-connection.md: AI/model/tool connection guide.

Known Product Gaps

  • Group video calls.
  • Full call invitation UI beyond browser confirm.
  • Admin dashboard for private relay owners.
  • Built-in SMTP setup wizard.
  • End-to-end encryption polish and verification UX.
  • Push notifications outside active browser session.