FrayBot - Telegram Spiritual Assistant (Magisterium AI)

FrayBot (@fray_holy_bot) answers as a digital Catholic priest using the Magisterium AI API. It only addresses religious topics and responds in the user's language with a calm, friendly tone.

Requirements

• Python 3.10+
• Magisterium AI account and API key
• Telegram bot token

Local setup (polling)

1. Install dependencies:

pip install -r requirements.txt

2. Copy the example env file and fill in your credentials:

cp env.example .env

Set in .env:

• MAGISTERIUM_API_KEY: your Magisterium key (keep it secret, do not commit).
• TELEGRAM_BOT_TOKEN: your Telegram bot token.

3. Run the bot:

python bot.py

The bot will start polling for messages.

Cloudflare Worker deployment (webhook)

There is a Cloudflare Worker version under cloudflare_worker/ for webhook-based operation (recommended for production).

Prerequisites

• Cloudflare account with a workers.dev subdomain (e.g., fraybot-worker.e1digital.workers.dev).
• A KV namespace for conversation context.

Configure

1. Install dependencies

cd cloudflare_worker
npm install

2. Create KV namespace and set IDs in wrangler.toml

npx wrangler kv namespace create CONTEXT_KV
# copy id/preview_id into wrangler.toml

3. Add secrets (per account)

npx wrangler secret put TELEGRAM_BOT_TOKEN
npx wrangler secret put MAGISTERIUM_API_KEY
# optional if you want webhook auth:
npx wrangler secret put TELEGRAM_SECRET_TOKEN

4. Deploy

npx wrangler deploy

The Worker should respond ready at https://<your-subdomain>.workers.dev/.

5. Register Telegram webhook (replace with your token and URL)

https://api.telegram.org/bot<TELEGRAM_BOT_TOKEN>/setWebhook?url=https://<your-subdomain>.workers.dev/telegram
# if you set TELEGRAM_SECRET_TOKEN, append: &secret_token=<same_value>

6. Check webhook status

https://api.telegram.org/bot<TELEGRAM_BOT_TOKEN>/getWebhookInfo

Observability

Logs are enabled via wrangler.toml ([observability.logs]). Tail logs with:

npx wrangler tail

Security notes

• Never hardcode or commit your real keys.
• Keep secrets in environment variables or .env (and keep the file untracked).

Bot behavior

• Responds only about Catholic faith, morality, prayer, and spiritual guidance.
• Tone: calm, empathetic, and respectful.
• Language: replies in the language detected from the user.
• Includes related questions if Magisterium returns them and shows citations when available.