GTS WebChat docsby GTS Team

WebChat › Docs › AI connection

AI connection

Source: docs/ai-connection.md · AI

This guide explains how an AI model, CLI worker, or tool process should connect to pChat as a visible participant.

Internal relay names may still say webchat or pchat; the user-facing app is pChat/WebChat depending on deployment branding.

Main docs index:

docs/index.md

High-level user and AI feature overview:

docs/high-level-features.md

Developer API reference:

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

CLI quickstart for new AI sessions:

docs/ai-session-quickstart.md

Use the CLI wrapper:

scripts/webchat_cli.py

The CLI creates a real relay persona, gives it a chat address, marks it online while watching, polls for messages, and can send messages/files through the same relay APIs used by the browser.

Live Test Identity

When a human tester asks another AI/session to join the same room, use one clear identity so it is easy to find in the relay directory:

Display name: Codex Test Side
Chat address: codex-test
Email: ai-codex@example.com
Relay: http://127.0.0.1:5110
Web app: http://127.0.0.1:8026/app/webchat/chat.html

In the browser, users can search for either Codex Test Side or codex-test. The directory search matches visible names and chat addresses.

Start A Local Relay

For local development:

./start_relay.sh
./start_web.sh

The relay is usually:

http://127.0.0.1:5110

The app is usually:

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

If a port is busy, the start scripts print the actual port they selected. Do not guess ports when multiple instances are running; copy the printed relay URL and web URL into the CLI flags below.

Create An AI Persona

Create a visible AI/tool identity:

scripts/webchat_cli.py ai-codex@example.com \
  --name "Codex Test Side" \
  --persona "Codex agent" \
  --computer "codex" \
  --session-name "live support" \
  --chat-address codex-test \
  --relay http://127.0.0.1:5110 \
  --site http://127.0.0.1:8026/app/webchat/chat.html

The output includes:

  • GUI auto-login URL
  • display name
  • email
  • chat address
  • session metadata

Give humans the chat address:

codex-test

Users can search the relay directory for the AI name or address and start a conversation.

Keep The AI Online And Listening

Run watch mode:

scripts/webchat_cli.py ai-codex@example.com \
  --name "Codex Test Side" \
  --persona "Codex agent" \
  --computer "codex" \
  --session-name "live support" \
  --chat-address codex-test \
  --relay http://127.0.0.1:5110 \
  --watch \
  --interval 2 \
  --limit 20

While this runs:

  • pChat presence shows the AI/tool session online.
  • Incoming messages print to stdout.
  • File and voice attachments print with their download URLs.
  • Ctrl-C stops the listener and sends offline presence.

Use --quiet-url for daemon logs:

scripts/webchat_cli.py ai-codex@example.com \
  --name "Codex Test Side" \
  --chat-address codex-test \
  --relay http://127.0.0.1:5110 \
  --watch \
  --quiet-url

Send A Reply

Send text from the AI persona:

scripts/webchat_cli.py ai-codex@example.com \
  --name "Codex Test Side" \
  --chat-address codex-test \
  --relay http://127.0.0.1:5110 \
  --to USER_CHAT_ADDRESS \
  --message "Hello, I am connected from the AI session."

Send a file:

scripts/webchat_cli.py ai-codex@example.com \
  --name "Codex Test Side" \
  --chat-address codex-test \
  --relay http://127.0.0.1:5110 \
  --to USER_CHAT_ADDRESS \
  --file ./report.pdf \
  --caption "Here is the report."

Send audio as a voice clip:

scripts/webchat_cli.py ai-codex@example.com \
  --name "Codex Test Side" \
  --chat-address codex-test \
  --relay http://127.0.0.1:5110 \
  --to USER_CHAT_ADDRESS \
  --file ./reply.webm \
  --attachment-kind voice \
  --caption "Voice response"

Open The AI Persona In The Browser

Generate a GUI session link:

scripts/webchat_cli.py ai-codex@example.com \
  --name "Codex Test Side" \
  --persona "Codex GUI" \
  --chat-address codex-test \
  --relay http://127.0.0.1:5110 \
  --site http://127.0.0.1:8026/app/webchat/chat.html

Open the printed URL. It includes:

  • server_url
  • display_name
  • chat_address
  • pchat_session
  • persona
  • computer_name
  • session_name
  • listen_channel

Do not paste this URL publicly; it contains a session token.

Private Relay

For a private relay:

scripts/webchat_cli.py ai-codex@example.com \
  --name "Codex Private Agent" \
  --chat-address codex-private \
  --relay https://relay.example.com \
  --relay-mode private \
  --watch

The same CLI commands work against public and private relays. Private relay operators should configure SMTP, HTTPS, backups, and appropriate access policy.

Direct API Path

Use direct HTTP only when you are not using the CLI.

Headers:

Content-Type: application/json
X-PChat-Session: pct_...

Send a message:

curl -s -X POST http://127.0.0.1:5110/api/v1/messages \
  -H "Content-Type: application/json" \
  -H "X-PChat-Session: pct_SESSION_TOKEN" \
  -d '{
    "phone_id": "pchat_free_phone",
    "channel": "pchat",
    "source": "codex-test",
    "to": "USER_CHAT_ADDRESS",
    "text": "Hello from the AI worker"
  }'

Poll inbox:

curl -s -X POST http://127.0.0.1:5110/api/v1/webchat/poll \
  -H "Content-Type: application/json" \
  -H "X-PChat-Session: pct_SESSION_TOKEN" \
  -d '{
    "phone_id": "pchat_free_phone",
    "chat_address": "codex-test",
    "limit": 20
  }'

Presence:

curl -s -X POST http://127.0.0.1:5110/api/v1/webchat/presence \
  -H "Content-Type: application/json" \
  -H "X-PChat-Session: pct_SESSION_TOKEN" \
  -d '{
    "chat_address": "codex-test",
    "display_name": "Codex Test Side",
    "visible": true,
    "device_name": "codex",
    "session_name": "live support",
    "listen_channel": "pchat"
  }'

Agent Loop Shape

A simple AI worker loop should:

  1. Start or reuse a pChat persona.
  2. Mark presence online.
  3. Poll inbox every 1-3 seconds.
  4. For each new message, pass text/attachment metadata to the model.
  5. Send the model response with --message or POST /api/v1/messages.
  6. Log the action locally.
  7. Send offline presence on shutdown.

Rules For AI Sessions

  • Always use a visible display name and stable chat address.
  • Do not impersonate a human user.
  • Do not join private groups unless the owner explicitly adds/invites the AI.
  • Do not read or export conversations outside the approved chat/session scope.
  • Do not edit/delete human messages unless the product owner explicitly grants that behavior.
  • CLI/AI sessions can send and receive text/files/voice attachments, but they cannot participate in browser WebRTC voice/video calls.