Pizzario Bot – Complete Setup & Operations Guide

Overview

This guide explains how to run and operate the Pizzario Telegram bot in a Docker container with minimal startup configuration, and how to configure all optional features directly within Telegram. It covers keys, hosting providers, payments, maps, domains, themes, language, support, notifications, and the admin dashboard.

Requirements

• Telegram account to manage the bot
• Docker installed on Windows or Linux
• Two environment variables ready: TELEGRAM_BOT_TOKEN and GEMINI_API_KEY
• Optional: Cloudflare account (Pages, R2), PayPal, Gumroad

Create Telegram Bot Token

1. Open Telegram and search for BotFather.
2. Send /newbot and follow prompts (choose a name and a unique username ending with bot).
3. BotFather returns a token like 123456:ABC-DEF.... Keep it secret.

Use this token as TELEGRAM_BOT_TOKEN when starting the container.

Create Gemini API Key

1. Go to Google AI Studio and sign in.
2. Create an API key under the Keys section.
3. Copy the key and store it securely.

Use this as GEMINI_API_KEY. The bot's AI assistant is immediately available after startup.

Build & Run Docker (Windows & Linux)

Windows (PowerShell)

docker build -t pizzario-bot .
docker run -e TELEGRAM_BOT_TOKEN=<token> -e GEMINI_API_KEY=<key> -p 3000:3000 -v pizzario-data:/app/data pizzario-bot

Linux (bash)

docker build -t pizzario-bot .
docker run -e TELEGRAM_BOT_TOKEN=<token> -e GEMINI_API_KEY=<key> -p 3000:3000 -v pizzario-data:/app/data pizzario-bot

Replace <token> with your actual bot token and <key> with your Gemini API key.

First-Run Wizard & Admin Lock

After startup, send /admin from your Telegram account. The first caller is permanently stored as the primary admin.

• Use /admin to access the admin dashboard.
• Use the "First Run Setup Wizard" buttons to configure AI, Hosting, Payments, Premium plan, and Maps.
• All changes are stored in SQLite; no container restart is required.

Admin Dashboard Usage

Open /admin. Controls include:

• List Users - View all users, their sites, and manage their accounts
• Support Tickets - View and respond to user support requests
• Setup Hosting - Configure Cloudflare Pages or R2 storage
• Setup Payment - Configure PayPal, Gumroad, or Telegram Stars
• Namesilo API Setup - Enable domain availability lookups
• AI Assistant - Get help from the built-in AI
• Documentation - Access documentation files
• Map Provider Setup - Choose Google Maps or OpenStreetMap
• Edit Premium Plan - Configure pricing and premium features
• Notifications - Configure admin notification preferences

Cloudflare Pages & R2 Tokens

To enable site deployment and image storage, you need to connect your Cloudflare account. This requires your Account ID and a custom API Token.

1. Get Your Account ID

1. Log in to the Cloudflare Dashboard.
2. Go to Workers & Pages on the left sidebar.
3. Look for "Account ID" on the right side of the Overview page.
4. Copy this ID (e.g., a1b2c3d4e5f6...).

2. Create API Token

You need a token with permissions for both Cloudflare Pages (hosting) and R2 (storage).

1. Go to My Profile → API Tokens.
2. Click Create Token.
3. Scroll down and click Get started next to "Create Custom Token".
4. Name the token (e.g., "Pizzario Bot").
5. Permissions: Add the following 3 permissions:
   • Account | Cloudflare Pages | Edit
   • Account | Workers R2 Storage | Edit
   • Account | Workers R2 Storage | Read
6. Account Resources: Select "Include" → "All accounts" (or your specific account).
7. Click Continue to summary → Create Token.
8. Copy the token immediately (you won't see it again).

3. Connect Inside the Bot

1. Open /admin → "Setup Hosting".
2. Choose "Cloudflare Pages" or "Cloudflare R2 Storage".
3. Paste the combined string: ACCOUNT_ID:API_TOKEN.

Maps: Google vs OpenStreetMap

Recommendation

Setup OSM

1. Open /admin → "Map Provider Setup".
2. Select "OpenStreetMap (free)".

Setup Google Maps

1. Create a Google Cloud project and enable:
   • Maps Embed API
   • Places API
   • Geocoding API
2. Create an API key; restrict it to your allowed environments.
3. Open /admin → "Map Provider Setup" → "Use Google Maps", then paste the API key when prompted.

Setup PayPal

1. Create a PayPal REST app and obtain Client ID and Client Secret.
2. Open /admin → "Payment Setup" → "PayPal".
3. Enter Client ID, then Client Secret, then choose Mode (sandbox or live).
4. Paste the Webhook Base URL (see detailed guide below).

The bot exposes POST /paypal/webhook and GET /health on the configured port.

Setup Gumroad

1. Open /admin → "Payment Setup" → "Gumroad".
2. Provide Product URL, Seller ID, and Billing Period (days).
3. Use "Connect Gumroad" to validate.

Setup Telegram Stars

1. Open /admin → "Payment Setup" → "Telegram Stars".
2. Set Stars Price and Billing Period.
3. Enable or disable as needed.

Webhook Base URL (Detailed Guide for Beginners)

The Webhook Base URL is one of the most important settings for accepting payments. Here's everything you need to know, explained step-by-step for non-technical users.

What is a Webhook URL?

Think of a webhook like a doorbell. When someone pays for your service through PayPal, PayPal "rings the doorbell" of your bot to tell it "Hey, someone just paid!" The Webhook URL is the address where PayPal knows to ring that doorbell.

Why Do You Need It?

• Without it, PayPal has no way to tell your bot when a payment is successful
• This means users won't automatically get their premium features activated
• You would have to manually check PayPal and upgrade users yourself

What Does a Webhook URL Look Like?

Choose Your Setup Method

Pick the option that best matches your situation:

sudo ufw allow 3000

How to Test If Your Webhook URL is Working

{"status":"ok","service":"pizzario-payment-gateway","timestamp":"2024-01-15T10:30:00.000Z"}

Troubleshooting: Common Problems and How to Fix Them

Notifications Setup

The Notifications feature allows you to stay informed about important events happening in your bot. As an admin, you can receive real-time alerts directly in Telegram.

How to Access Notifications Settings

1. Open /admin in Telegram
2. Click on "🔔 Notifications"
3. Configure your notification preferences

Available Notification Types

How to Enable/Disable Notifications

1. Navigate to /admin → "Notifications"
2. Toggle each notification type on or off
3. Settings are saved automatically

Notification Format

Notifications are sent as Telegram messages with relevant details:

🆘 New Support Ticket #42

👤 User: @john_pizza (12345678)
📋 Issue: Website Customization
📝 Description:
I want to change my menu layout...

Best Practices

• Enable support ticket notifications - Respond quickly to user issues
• Enable payment notifications - Stay informed about revenue
• Consider disabling customization notifications if you have many active users to avoid notification overload

📢 Bulk Messages

Send broadcast messages to all your bot users (everyone who has started the bot). This is great for announcements, promotions, or updates.

How to Send

1. Open /admin → "📢 Bulk Messages".
2. Click "✉️ Create New Message".
3. Step 1: Send the text content for your message. You can use emojis!
4. Step 2: Optionally attach an image. Send a photo or type "no" to skip.
5. Step 3: Choose when to send:
   • 🚀 Send Now: Starts sending immediately (within 1 minute).
   • ⏰ In 1 Hour: Schedules for later.
   • 📅 In 24 Hours / 1 Week: Good for planned promotions.

Managing Messages

• View Scheduled: Click "📋 View Scheduled Messages" to see upcoming and recent messages.
• Status: You can see how many users received the message and if any failed.
• Cancel: You can cancel any message that is still "Pending" (hasn't started sending yet).

Premium Plan Configuration

1. Open /admin → "Edit Premium Plan".
2. Edit Plan Name, Price, Billing Period.
3. Toggle features (Language, Offer, Domain, Templates, Customize) between Free and Premium.

Namesilo & Manual Domain Linking

Option 1: Manual Domain Linking (Any Registrar)

If you purchase a domain for a user manually (e.g., from Namecheap, GoDaddy, or Namesilo), follow these steps to link it to their site:

1. Get the User's Site URL: Ask the user for their current site link (e.g., https://pizzeria-1234.pizzariobot.com).
2. Configure DNS: Go to your domain registrar's DNS settings for the new domain.
   • Create a CNAME record.
   • Host: @ (or www)
   • Value/Target: The user's current site URL (without https://).
   • Example: Point mypizza.com to pizzeria-1234.pizzariobot.com.
3. Wait for Propagation: DNS changes can take 15-30 minutes.
4. Inform the User: Tell the user their new domain is ready! They can now use mypizza.com to access their site.

Option 2: Namesilo API (Automated)

If you have a Namesilo account, you can let users search for domains directly in the bot.

1. Open /admin → "Namesilo API Setup".
2. Paste your Namesilo API key.
3. Users can now use /domain to search for available domains.
4. If they request a domain, you (the admin) will get a notification to approve/buy it manually.

Add More Themes

1. Add new template HTML files to the templates directory.
2. Users can then select the new template via /templates.
3. Publish changes to apply the theme.

Add More Languages

1. Enable Language feature as Free or Premium in the Premium Plan.
2. Users can change their site language and republish.

Rename the Bot

1. Open BotFather in Telegram.
2. Use /setname and /setdescription to update display name and description.

Token remains unchanged. Users see the new name immediately.

Ask the AI Assistant

Use /ai <question> at any time for setup help, troubleshooting, or best practices. The assistant is available immediately after startup.

Health Check & Ports

• Single HTTP port for webhooks and health: PORT env, default 3000.
• Health endpoint: GET /health returns 200 and status JSON.
• Graceful shutdown: SIGINT/SIGTERM close bot polling, HTTP server, and DB connections.

How Users Generate a Site

1. Send /start and follow onboarding prompts.
2. Share GPS location to auto-detect country, currency, and phone code.
3. Enter your pizzeria name and phone number.
4. Use the "Add Your Pizza Menu" button to create your menu.
5. Optionally add pizza images and social media links.
6. Your site will be published and you'll receive the URL!

Edit Main Offer (Hero)

The offer appears in the hero section at the very top of your website. It's the first thing visitors see!

1. Send /offer to start editing.
2. Enter your offer title (e.g., "50% OFF TODAY!").
3. Enter your offer description (e.g., "Use code PIZZA50").
4. Click "Redeploy Now" to publish changes.

Change Language

1. Send /language to see available languages.
2. Select your preferred language.
3. Click "Apply Now" to republish your site in the new language.

Customize the Site

Pizza Menu

Use the Web App button during onboarding to enter your pizzas, prices, and categories. You can update and republish at any time by using /customize.

Site Logo

Go to /customize → "Change Logo" and upload your logo image. The bot will resize it automatically.

About Us Section

Use /customize → "Edit About Us" to add a personal description and image for your restaurant.

Social Pages

Add your Facebook, Instagram, and X (Twitter) links during onboarding or via /customize.

Edit Location

Use /customize → "Edit Location" to update your address. The map on your website will update automatically.

Search Domain & Send to Admin

1. Send /domain to start.
2. Choose "Single Search" or "Bulk Search".
3. Enter domain names without .com (e.g., "mypizzashop").
4. If available, click "Send to Admin for Approval".
5. The admin will review and link the domain to your site.

Contact Support

1. Send /support to open the help desk.
2. Select the topic that matches your issue.
3. Describe your problem in detail.
4. The admin will respond directly to you in Telegram.
5. Use "My Ticket History" to view past conversations.

Frequently Asked Questions

How much does it cost?

Creating a basic website is free! Premium features (custom domain, advanced templates, offers) require a subscription.

How do I update my menu?

Use /customize → "Edit Menu" to add, remove, or modify your pizza items.

Can I have multiple websites?

Currently, each Telegram account can have one website. Contact support if you need additional sites.

How do customers order?

Your website has a WhatsApp button that allows customers to send orders directly to your phone number.

Is my website mobile-friendly?

Yes! All templates are fully responsive and look great on phones, tablets, and computers.