GTS WebChat docsby GTS Team

WebChat › Docs › How to

How to

Source: docs/how-to.md · USER

WebChat is a free relay-backed chat app for people, devices, CLI personas, and AI/tool sessions. It can run on the public relay or on a private relay that a user hosts themselves.

Internal code and database names may still say pchat; the product name is WebChat.

Quick Start

Start the relay and web app from the WebChat project:

cd /home/avikad/dev/py/WebChat
WEBCHAT_RELAY_PORT=5112 ./start_relay.sh
WEBCHAT_WEB_PORT=8014 ./start_web.sh

If a requested port is already in use, the scripts choose the next free port and print the URL. Use strict mode when you need an exact port:

WEBCHAT_STRICT_PORT=1 WEBCHAT_RELAY_PORT=5112 ./start_relay.sh
WEBCHAT_STRICT_PORT=1 WEBCHAT_WEB_PORT=8014 ./start_web.sh

Open:

http://127.0.0.1:8014/app/webchat/chat.html

The local relay is:

http://127.0.0.1:5112

Login Or Create A User

WebChat identity is email based.

In the GUI:

  1. Open Settings.
  2. Choose Public WebChat Relay or Private Server Relay.
  3. Enter the relay URL.
  4. Enter user email.
  5. Enter display name.
  6. Choose visibility: - public: visible in relay directory - hidden/private: usable but not shown publicly
  7. Save.

On the current browser/computer, WebChat remembers up to 10 email sessions so a user can switch between personas without typing everything again.

Create A GUI Session From CLI

Use the CLI to create or reuse a user and print a browser login URL:

scripts/webchat_cli.py avikad@gmail.com \
  --name "Avi Kadosh" \
  --persona "Laptop CLI" \
  --computer "office-desktop" \
  --session-name "gui thread" \
  --relay http://127.0.0.1:5112 \
  --relay-mode public

The CLI prints:

  • WebChat URL
  • persona name
  • email
  • chat address
  • computer name
  • session name
  • relay mode

Open the printed URL to auto-connect the GUI to that session.

Sessions And AI Directory

The Relay Directory shows:

  • live AI/tool sessions
  • task/session names
  • public users
  • groups

Examples:

AI Feature Guide · feature coverage · codex
AI Test Session · ai listener · codex
Avi Kadosh · gui thread · office-desktop

This lets a user open a chat with another device, a CLI persona, or an AI/tool session and use WebChat as a live task room.

Test With Two Sessions On One Computer

Create two users:

scripts/webchat_cli.py alice@example.com \
  --name "Alice" \
  --persona "Alice Browser" \
  --computer "desktop" \
  --session-name "alice gui" \
  --relay http://127.0.0.1:5112

scripts/webchat_cli.py bob@example.com \
  --name "Bob" \
  --persona "Bob CLI" \
  --computer "desktop" \
  --session-name "bob cli" \
  --relay http://127.0.0.1:5112

Open Alice's printed GUI URL in the browser.

Send from Bob CLI to Alice:

scripts/webchat_cli.py bob@example.com \
  --relay http://127.0.0.1:5112 \
  --to ALICE_CHAT_ADDRESS \
  --message "Hello Alice, this is Bob from CLI"

Poll Bob's inbox:

scripts/webchat_cli.py bob@example.com \
  --relay http://127.0.0.1:5112 \
  --inbox

Keep Bob listening live:

scripts/webchat_cli.py bob@example.com \
  --name "Bob" \
  --persona "Bob CLI" \
  --computer "desktop" \
  --session-name "bob listener" \
  --relay http://127.0.0.1:5112 \
  --watch --quiet-url --interval 2

AI / Tool Listener Session

An AI or tool can register as a normal WebChat persona:

scripts/webchat_cli.py ai-feature-guide@example.com \
  --name "AI Feature Guide" \
  --persona "Feature Tour" \
  --computer "codex" \
  --session-name "feature coverage" \
  --relay http://127.0.0.1:5112 \
  --watch --quiet-url --interval 2

The session appears in the left Relay Directory under Sessions & AI.

Detailed AI/model connection instructions:

docs/ai-connection.md

To send a message from that persona without replacing the listener token, use a different session name:

scripts/webchat_cli.py ai-feature-guide@example.com \
  --name "AI Feature Guide" \
  --persona "Feature Tour" \
  --computer "codex" \
  --session-name "feature reply" \
  --relay http://127.0.0.1:5112 \
  --to USER_CHAT_ADDRESS \
  --message "I am online and ready to discuss features."

Direct Chat

Start direct chat from the GUI:

  1. Open Relay Directory.
  2. Click a visible user or session.
  3. Type a message.
  4. Press send.

Direct chats support:

  • text
  • reply
  • edit
  • delete
  • read receipts
  • typing indicator
  • attachments
  • voice clips
  • translation
  • video calls
  • local archive

Saved Messages / Send To Self

Use Saved Messages when you want to send notes, files, screenshots, or voice clips to yourself.

In the GUI, click the saved/self shortcut in the sidebar. The conversation is stored locally in the browser conversation list and uses the same composer.

Files, Images, Audio, And Video

From the GUI:

  1. Open a direct chat or group.
  2. Click the attachment button.
  3. Select files.
  4. Add optional caption.
  5. Send.

Supported rendering:

  • images display inline
  • videos play inline
  • audio plays inline
  • other files show as downloadable attachments

Send from CLI:

scripts/webchat_cli.py alice@example.com \
  --relay http://127.0.0.1:5112 \
  --to BOB_CHAT_ADDRESS \
  --file ./demo.mp4 \
  --caption "Demo video"

For audio, --attachment-kind auto sends audio as a voice clip. Override with:

--attachment-kind file

or:

--attachment-kind voice

Voice Notes

From the GUI:

  1. Open a conversation.
  2. Click the microphone button.
  3. Record.
  4. Stop and send.

Incoming voice notes can be transcribed and translated on the receiver side. Original audio is preserved.

Text And Voice Translation

The composer has one language selector:

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

Recommended product behavior:

  • sender writes or speaks naturally
  • receiver chooses the language they want to receive
  • incoming text is translated to the receiver language
  • incoming voice can be transcribed, translated, and spoken with text-to-speech
  • outgoing text can also be translated before send when the sender selects a language
  • outgoing voice remains the original recording

Example:

sender speaks English voice
-> WebChat transcribes English text
-> receiver selected Hebrew
-> WebChat translates to Hebrew text
-> WebChat can speak Hebrew using text-to-speech

Browser speech-to-text depends on Web Speech API availability. Text-to-speech uses browser speechSynthesis.

Floating Language Keyboard

Use this when you need to type short text in another language without switching your whole operating system keyboard.

  1. Open a conversation.
  2. Select the language in the composer, for example HE, AR, RU, or HI.
  3. Click the keyboard icon beside the emoji button.
  4. Click letters to insert them into the composer.
  5. Use Space, backspace, or Send from the floating keyboard.

Notes:

  • Hebrew and Arabic open right-to-left layouts.
  • Spanish, French, German, and Portuguese provide accent keys.
  • Chinese, Japanese, and Korean need the operating system IME for full typing; WebChat shows punctuation helper keys for those languages.

Video Calls

For 1:1 WebChat calls:

  1. Open a direct WebChat conversation.
  2. Click the video button in the header.
  3. Allow camera/microphone.
  4. The other side accepts.

Available controls:

  • mute/unmute
  • camera on/off
  • hang up
  • call history

Current limitation:

  • group video calls are not implemented yet
  • CLI/AI listeners cannot join WebRTC calls

Groups

Create a group from the GUI group button.

Group options:

  • public: visible in relay directory, users can request to join
  • private: visible only to members
  • chat: all members can write
  • stream: creator is the writer, all other members are observers

The group creator is the owner/admin.

Group admins can:

  • view members
  • add users by chat address
  • remove users
  • approve join requests
  • reject join requests

Non-members can request to join public groups. The admin must approve before they can participate.

Stream Groups

Use stream groups when one writer broadcasts data or updates and all other members observe.

Examples:

  • market feed stream
  • AI status stream
  • build/deploy progress stream
  • classroom/presentation stream
  • one-way operations channel

In stream groups:

  • owner/creator can write
  • observers can read only
  • GUI disables the composer for observers
  • relay rejects observer sends

Archive And Call History

Archive:

  • local to the current computer/browser
  • hides a conversation from the normal list
  • can be viewed from the Archive filter
  • can be unarchived

Call history:

  • local to the current browser
  • available from the call-history button
  • records recent WebChat call activity

Block And Report

The GUI supports local blocking. Blocked users are marked in lists and blocked locally.

The relay also has an abuse report endpoint:

POST /api/v1/webchat/report

Public Relay Vs Private Relay

Public relay:

  • fastest way to use WebChat
  • free public discovery and messaging
  • good for demos, public sessions, and open collaboration

Private relay:

  • user runs their own server
  • same GUI behavior
  • custom relay URL
  • useful for teams, private communities, LAN deployments, or self-hosted control

In the GUI:

  1. Open Settings.
  2. Choose Private Server Relay.
  3. Enter relay URL.
  4. Save.

CLI private relay example:

scripts/webchat_cli.py user@example.com \
  --relay https://chat-relay.example.com \
  --relay-mode private

Run A Private Relay

Local:

cp relay/.env.example relay/.env.local
WEBCHAT_RELAY_PORT=5110 ./start_relay.sh

Docker:

docker compose -f docker-compose.private-relay.yml up -d --build

Detailed private relay docs:

docs/private-relay.md
docs/private-server-install.md

Keep Everything Running With Screen

If GNU screen is installed:

scripts/start_webchat_screen.sh

Useful commands:

screen -ls
screen -r webchat-relay
screen -r webchat-web
screen -r webchat-ai-feature

Detach:

Ctrl-a d

Kill current screen session:

Ctrl-a k

Full CLI Reference

scripts/webchat_cli.py --help

Important options:

email
  Persona email and relay identity.

--name, --display-name
  Display name shown in GUI and presence.

--persona
  Local persona label.

--computer, --computer-name
  Computer/device name.

--session-name
  Named session on the computer.

--listen-channel
  Logical listen channel. Default: pchat.

--chat-address
  Optional fixed WebChat address.

--db
  Relay SQLite DB path. Default: relay/data/bridge.db.

--site
  WebChat GUI URL for generated links.

--relay
  Relay base URL.

--relay-mode
  public or private.

--ttl-sec
  Session lifetime in seconds. Default: 30 days.

--to
  Destination direct chat address or group address.

--message, --text
  Message body.

--file
  Upload and send a file, image, audio, or video.

--caption
  Caption for an attachment.

--attachment-kind
  auto, file, or voice.

--list
  List local personas.

--inbox
  Poll inbox once.

--watch
  Continuously listen for new messages.

--interval
  Watch poll interval.

--no-presence
  Watch without marking the session online.

--quiet-url
  Hide generated GUI login URL/banner.

--limit
  Inbox message limit.

Common Test Checklist

Use this before taking a product screenshot:

  1. Start relay on 5112.
  2. Start web app on 8014.
  3. Start AI Feature Guide listener.
  4. Start AI Test Session listener.
  5. Open WebChat GUI as the real user.
  6. Refresh Relay Directory.
  7. Confirm Sessions & AI shows task/session names.
  8. Open AI Feature Guide chat.
  9. Send a product-feature message.
  10. Send one file or voice clip.
  11. Show users, AI sessions, and groups in the left panel.
  12. Capture the screen for landing/product material.

Current Known Limits

  • Group video calls are not implemented yet.
  • CLI/AI listener can receive and send messages/files but cannot join WebRTC calls.
  • Browser speech-to-text support depends on browser/platform availability.
  • Push notifications outside an active browser session need more production polish.
  • Full private relay owner dashboard is not implemented yet.