🕊️ UniSoul — Spiritual Guide Telegram Bot

UniSoul is a modern Telegram bot built with Laravel 12 and PHP 8.2, designed as a spiritual guide with confession flows, configuration menus, and an admin panel powered by Filament.

⚠️ Project status: Testing / Demo-ready

---

🎥 Demo Videos

• Bot Demo (User Flow):
  https://youtu.be/zdwysA-RAVQ

• Admin Panel & Management Demo:
  https://youtu.be/hal26y43olA

---

🚀 Try This Bot

You can interact with the live demo bot directly on Telegram:

👉 https://t.me/unis1oul_bot

This demo showcases:

• Main menu navigation
• User configuration flows
• Confession and message handling
• Real production bot behavior

✨ Features

• Telegram bot with structured conversational flows
• User configuration (language, notifications, gender, etc.)
• Confession and message storage
• Filament admin panel for moderation and statistics
• Docker-first setup with Laravel Sail
• Prepared for polling and webhook modes
• Laravel 12 & PHP 8.2 compatible architecture

---

🧱 Tech Stack

• Backend: Laravel 12, PHP 8.2
• Bot Framework: Nutgram
• Admin Panel: Filament
• Database: MySQL
• Infrastructure: Docker, Laravel Sail
• Cache / Queue Ready: Redis (optional)

---

📸 Screenshots

🤖 Bot Interface

Confession Actions	Contact & Chat Form
Main menu and confession flow	User contact and chat interaction

---

🎥 Demo Video

Click to view demo

unisoul.mp4

🛠️ Admin Panel (Filament)

Bot Buttons Management	Confessions Management
Configure bot keyboards and actions	Moderate and review user confessions

---

🚀 Installation & Setup

Requirements

• Docker
• Docker Compose

---

1. Environment Configuration

Copy .env.example to .env and configure:

APP_ENV=local
TELEGRAM_BOT_TOKEN=YOUR_BOT_TOKEN

DB_CONNECTION=mysql
DB_HOST=mysql
DB_PORT=3306
DB_DATABASE=laravel
DB_USERNAME=sail
DB_PASSWORD=password

---

2. First Run (Docker)

docker compose up -d
docker compose exec bot.backend composer install
docker compose exec bot.backend php artisan migrate

---

3. Daily Usage (Sail)

./vendor/bin/sail up -d
./vendor/bin/sail down

---

🤖 Bot Execution Modes

Polling Mode (Default — Dev & Prod)

Configured via supervisord:

• docker/8.4/supervisord.conf (local)
• docker/production/supervisord.conf (production)

Run manually if needed:

./vendor/bin/sail artisan nutgram:run

---

Webhook Mode (Optional)

Prepared but disabled by default.

Enable webhook after deployment:

php artisan nutgram:hook:set https://yourdomain.com/api/telegram/webhook

Check status:

php artisan nutgram:hook:info

Remove webhook:

php artisan nutgram:hook:remove

Webhook endpoint:

POST /api/telegram/webhook

(CSRF excluded)

---

🧪 Testing

./vendor/bin/sail artisan test

Includes feature tests for webhook handling and database persistence.

---

🛠️ Admin Panel (Filament)

URL: http://localhost:8050/management

Default Admin Users (Seeded)

Email	Password
default@admin.test	password
test@admin.test	password

Resources:

• Users
• Confessions
• Bot Buttons
• Statistics

Create new admin:

./vendor/bin/sail artisan make:filament-user

🔄 Core Bot Flows

The bot supports a minimal, command-driven interaction model. All user actions are handled via explicit Telegram commands or free-text input.

Supported Commands

Command	Purpose
/start	Initialize user session and show main menu
/help	Display help and available commands
/settings	Open user settings menu

---

Behavior Matrix

Action / Input	Bot Behavior	Persistence Layer
/start	Initialize user, show main menu	UserConfig, UserMessage
/help	Show help text and command list	—
/settings	Show current user configuration	UserConfig
Change language	Update language preference	UserConfig
Toggle notifications	Enable / disable notifications	UserConfig
Free text message	Acknowledge or route based on state	UserMessage

---

Flow Notes

• /start is idempotent — safe to call multiple times
• /help is stateless — does not modify user data
• /settings operates only on existing users (created via /start)
• Free text messages are handled based on the current user state, not blindly echoed

---

Architecture

All Telegram interaction logic is centralized in:

app/Services/TelegramBotService.php

This service is responsible for:

• Command routing
• State resolution
• Message dispatch
• Persistence coordination (UserConfig, UserMessage)

---

🧩 Laravel 12 Compatibility Fixes

• Updated middleware signatures
• Modern Http\Kernel.php
• Webhook route using controller array syntax
• CSRF exclusion for Telegram webhook
• Strong typing for PHP 8.2
• Service-based bot architecture

---

📄 License

MIT License

---

📬 Contact

This project is suitable as:

• Portfolio demo
• SaaS Telegram bot base
• Client-ready bot foundation

For customization or integration — open an issue or contact the author.