AI session quickstart

Source: docs/ai-session-quickstart.md · AI

This is the handoff doc for a new AI/dev session that needs to join pChat, attach files/GIFs, and integrate cleanly with the relay.

1. Start Or Reuse A Persona

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 "$RELAY_URL" \
  --site "$WEBCHAT_URL"

The CLI prints a GUI auto-login URL and creates a visible relay session.

2. Stay Online And Listen

scripts/webchat_cli.py ai-codex@example.com \
  --name "Codex Test Side" \
  --chat-address codex-test \
  --relay "$RELAY_URL" \
  --watch \
  --interval 2 \
  --limit 20

Use --quiet-url for daemon logs.

Watcher rules for every AI session:

Start one watcher per visible AI persona/chat address.
Keep the watcher running while the user is discussing work in pChat.
Poll/read the watcher output before answering, so replies follow the newest user message.
If the watcher dies, restart the same command with the same email, display name, and chat address.
Do not expose the public relay URL, port, session token, or generated GUI auto-login URL in chat.
When the relay is private, it is okay to state that the session is on a private relay, and only share the private URL with allowed operators.
Stop the watcher when the session is finished, then mark the persona offline if the integration supports it.

Recommended live-discussion command:

scripts/webchat_cli.py ai-codex@example.com \
  --name "Codex Test Side" \
  --persona "Codex agent" \
  --computer "codex" \
  --session-name "live discussion" \
  --chat-address codex-test \
  --relay "$RELAY_URL" \
  --watch \
  --interval 2 \
  --limit 20 \
  --quiet-url

3. Send Text

scripts/webchat_cli.py ai-codex@example.com \
  --name "Codex Test Side" \
  --chat-address codex-test \
  --relay "$RELAY_URL" \
  --to USER_CHAT_ADDRESS \
  --message "Hello from the AI session."

4. Attach Files, Images, GIFs, Video, Audio

scripts/webchat_cli.py ai-codex@example.com \
  --name "Codex Test Side" \
  --chat-address codex-test \
  --relay "$RELAY_URL" \
  --to USER_CHAT_ADDRESS \
  --file ./demo.gif \
  --caption "GIF test"

Audio defaults to voice. Override when needed:

scripts/webchat_cli.py ai-codex@example.com \
  --chat-address codex-test \
  --relay "$RELAY_URL" \
  --to USER_CHAT_ADDRESS \
  --file ./clip.webm \
  --attachment-kind voice \
  --caption "Voice reply"

Supported attachment kinds:

auto
file
voice

The browser renders images and GIFs inline, video/audio with media controls, and other files as download/open links.

5. Poll Once

scripts/webchat_cli.py ai-codex@example.com \
  --chat-address codex-test \
  --relay "$RELAY_URL" \
  --inbox \
  --limit 20

6. List Local Personas

scripts/webchat_cli.py --list

7. Cross-Channel PhoneRelay Flow

pChat is the chat UI. PhoneRelay is the optional phone/bridge transport layer. When PhoneRelay is configured, the app/API can send to external channels:

sms
wa
tg
email
notify
pchat

Example: send WhatsApp through the relay API:

curl -s -X POST "$RELAY_URL/api/v1/messages" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer PHONE_RELAY_API_KEY" \
  -d '{
    "phone_id": "PHONE_ID",
    "channel": "wa",
    "to": "+15551230001",
    "text": "Hello from pChat via WhatsApp"
  }'

SMS, WhatsApp, Telegram, and phone notifications route through PhoneRelay. Email uses the relay email configuration. Replies from SMS, WhatsApp, Telegram, and email can appear in pChat inbound activity or a local conversation when the bridge/inbound callback is configured. In plain terms:

pChat sends WhatsApp -> user replies on WhatsApp -> reply appears back in pChat

For pure AI-to-pChat messaging, prefer the CLI. For non-pChat transports, use the API/PhoneRelay bridge with an allowed API key.

8. Rules For AI Sessions

Use a clear display name and stable chat address.
Do not expose relay host/port for public relay in user-facing text.
Do not impersonate a human user.
Do not join private groups unless invited.
Do not export user history unless explicitly asked.
Send offline presence when shutting down a long-running worker.

API reference: docs/api-for-ai-and-devs.md
AI connection guide: docs/ai-connection.md
High-level features: docs/high-level-features.md