Skip to content

PF_SIGNAL_BOT_RUNBOOK.md

Latest commit

 

History

History
164 lines (110 loc) · 4.35 KB

PF_SIGNAL_BOT_RUNBOOK.md

File metadata and controls

164 lines (110 loc) · 4.35 KB
Raw

PF Signal Bot Runbook

This repo is currently run as the Docker Compose project pf_signal_bot.

Start

docker-compose -p pf_signal_bot up -d --build

Check Status

docker-compose -p pf_signal_bot ps
Invoke-RestMethod -Uri http://localhost:8000/health

Expected health:

{"status":"ok","signal_gateway":"ok","database":"ok"}

Signal Account Check

Invoke-WebRequest -Uri http://localhost:8080/v1/accounts -UseBasicParsing

The bot number in .env must match the account returned by Signal REST. Use E.164 format with a leading +.

Update Bot Profile

Set username and display name:

docker-compose -p pf_signal_bot run --rm app python scripts/update_signal_profile.py --username PFSignalBot --name "PF Signal Bot"

Set avatar from an image file:

docker-compose -p pf_signal_bot run --rm app python scripts/update_signal_profile.py --avatar .\bot-avatar.png

Signal may return the final username with a discriminator, depending on availability.

Inbound Read/Reply Flow

The receiver service keeps a WebSocket open to Signal REST:

docker logs --tail 120 pf_signal_bot-receiver-1

Expected containers include:

  • pf_signal_bot-app-1
  • pf_signal_bot-worker-1
  • pf_signal_bot-receiver-1
  • pf_signal_bot-postgres-1
  • pf_signal_bot-signal-cli-rest-api-1

Authorize Group Access

  1. Add the bot Signal account to a group.
  2. Send any message in that group so the bot observes the group and sender membership.
  3. If your Signal number is configured in SIGNAL_ADMIN_NUMBERS, authorize from Signal:
!authorize this group

You can also DM the bot:

!groups
!authorize <GROUP_ID>
!access <SIGNAL_NUMBER>

The first successful !authorize this group sends a one-time intro message into the group. To resend that intro later, an admin can send !intro this group.

  1. Or list observed groups through the Admin API:
$token = ((Get-Content .env | Where-Object { $_ -match '^ADMIN_API_TOKEN=' }) -split '=',2)[1].Trim()
Invoke-RestMethod -Uri http://localhost:8000/admin/groups -Headers @{ Authorization = "Bearer $token" }
  1. Authorize the group through the Admin API:
Invoke-RestMethod -Method Post -Uri http://localhost:8000/admin/groups/<GROUP_ID>/authorize -Headers @{ Authorization = "Bearer $token" }

After that, DMs from users recently observed in that authorized group are eligible for replies. DMs from users only seen in ingest-only groups, ignored groups, or no groups are denied.

See ADMIN_APPROVAL_WORKFLOW.md for the full Signal-admin workflow.

Group auto-replies are gated separately. With GROUP_AUTO_REPLY_REQUIRE_MENTION=true, the bot ingests group traffic but only replies in a group when the message mentions the bot through Signal mention metadata or plain text such as @pfbot.

Conversation Threading

The bot treats each DM or group mention as a fresh request by default. It only treats a message as a continuation when the user directly replies to/quotes a previous Signal message. In that case, the quoted message id/text is passed to the model as local thread context for that one answer.

Admin Quality Of Life

Signal admin commands now include:

!status
!groups
!intro this group
!label this group <alias>
!label <group_id> <alias>
!authorize this group
!authorize <group_id_or_alias>
!ingest-only <group_id_or_alias>
!ignore <group_id_or_alias>
!reply-mode <group_id_or_alias> silent|mention|questions
!access <signal_number>

Reply modes:

  • silent: ingest only, never group-reply.
  • mention: group-reply only when tagged.
  • questions: group-reply only when tagged and the message has ?.

Unauthorized users can DM why to get a non-sensitive access explanation.

Conversation Exports

Every newly stored inbound message is appended to:

exports/conversations.jsonl
exports/conversations.csv

These files are local operational exports and are ignored by git.

Prompt Customization

Use .env for high-level behavior:

BOT_SYSTEM_PROMPT=
BOT_PERSONA_FILE=

The app always appends non-overridable privacy, retrieval, and threading rules after any custom prompt/persona.

Stop

docker-compose -p pf_signal_bot down

Do not remove Docker volumes unless you intentionally want to delete local Signal/Postgres state.