Install & activate
ShopGram is a single WooCommerce plugin. There is no companion service to deploy — your WordPress site talks to the Telegram Bot API directly.
- Upload the plugin
In WP-admin go to Plugins → Add New → Upload Plugin, choose the
shopgram.zipand click Install Now. - Activate
Click Activate Plugin. The plugin requires WooCommerce 7.0+; if it isn't installed the activation notice will tell you so.
- Open ShopGram → Settings
A new ShopGram entry appears in the WP-admin menu. The first screen is the connection wizard — that's where this guide starts.
Create a Telegram bot
Everything — storefront, chat, payments, admin notifications — runs through one bot. You only need to do this once.
- Talk to @BotFather
Open @BotFather in Telegram, send
/newbotand follow the prompts. Pick a public-facing display name and a unique@usernameending inbot. - Copy the bot token
BotFather replies with an HTTP API token — a long string like
123456:ABC-DEF…. Keep it: you'll paste it into the Telegram Connection tab in a moment. - (Optional) Set commands and Mini App short-name
Send
/setcommandsin BotFather to register slash-commands shown in the bot menu (start,orders,help). If you plan to use a Direct Link Mini App, also send/newappto register a short-name.
One bot is enough. The shop, the chat widget, the AI assistant, the admin notifications and the email mirror all share the same bot. The plugin separates them by chat ID and topic.
Telegram Shop
This tab controls the Mini App storefront — the Telegram-native shop that opens inside the messenger.
Mini App URL
The URL Telegram WebApp will open. By default it's /shopgram-app/ on your site — a virtual page registered by the plugin. You only need to change it if your front-end is hosted elsewhere (e.g. headless storefront).
Welcome message and keyboard
What the user sees when they send /start to your bot in a private chat. The welcome inline-keyboard exposes "Shop" and "Account" shortcuts (initData is delivered, so the buyer is authenticated); below it a reply keyboard offers Q&A buttons that simply echo the trigger phrase.
Q&A triggers
Pairs of trigger label → response. The label is rendered as a tappable button under the chat input, and any free-text message that matches the trigger gets the configured response (optionally with a photo attachment). Useful for FAQ — payment methods, shipping, returns.
Attribute mapping (variations)
Map WooCommerce product attributes to Mini App selectors. If your "Size" attribute is global, ShopGram renders it as a chip group; if it's per-product, it falls back to a dropdown. Color attributes get swatch chips automatically when the attribute term has a hex value.
Telegram Connection
Paste the bot token, register the webhook, and connect the supergroup that will receive orders, chats and notifications. Everything else depends on this tab being green.
Bot token
Paste the token that @BotFather gave you. Click Test connection to ping getMe — the bot's @username and display name should appear on success. The token is stored encrypted in the shopgram_settings option.
Webhook secret
Auto-generated on first save. ShopGram registers a webhook at /wp-json/shopgram/v1/tg-webhook and asks Telegram to send this secret in the X-Telegram-Bot-Api-Secret-Token header on every update. Updates without a matching secret are rejected.
Connect a supergroup
Generate a one-time registration token and paste /start_admin <token> into the Telegram supergroup you want to use. The bot must be admin and the group must have Topics enabled (so each visitor chat and the notification stream can live in its own topic). On success the bot replies with a confirmation and the tab flips to green.
Topics required. ShopGram uses one topic per order-events stream and one topic per visitor in the live chat. A regular group without topics will fail to register.
HTTP/HTTPS proxy (optional)
If your server can't reach api.telegram.org directly, point ShopGram at a SOCKS5/HTTP proxy here. The "Test proxy" button calls getMe via the candidate proxy and reports the result inline.
Admin Notifications
Forward WooCommerce order events into a Telegram topic so your team is notified the moment a sale lands.
Events
- New order — fires on
woocommerce_new_order. Card includes line items, customer, total, payment method. - Status change — every
woocommerce_order_status_*transition. Useful for "processing → completed" hand-offs. - Failed only — quieter alternative: only notify on
failed. Pair with Status change off if your team just wants to chase payments that bounced.
Topic
Pick an existing topic in the connected supergroup or let ShopGram create a fresh one called ShopGram · orders. The picker is populated by observing forum-topic events (Bot API doesn't expose a list endpoint).
Test message
Sends a small "hello from ShopGram" card into the chosen topic so you can verify the wiring without waiting for a real order.
Email Notifications
Mirror transactional WooCommerce emails into a Telegram topic. Useful as an archive or as a faster heads-up than email push notifications.
How it works
ShopGram hooks the wp_mail filter at priority 99 — late enough that any SMTP/From rewrites have already happened. For every outbound mail it forwards To, Subject and a short preview into the configured topic.
Filter by recipient or keyword
If you only want a subset (e.g. customer order emails, not password resets), enable the filter and list the recipients or subject keywords to allow. Everything else is ignored.
Privacy
Email bodies are forwarded in plain text with HTML stripped. If you'd rather not pipe customer addresses into Telegram, leave this tab disabled — the rest of ShopGram works fine without it.
Payments
Two WooCommerce payment gateways tied to the Mini App: Telegram Payments (card) and Telegram Stars. Both are invisible on the regular web checkout — they only appear when the buyer is inside Telegram.
Telegram Payments (card)
Customer pays by card inside Telegram's native payment sheet — no top-level redirect. Funds settle into the provider account you connect in @BotFather → Payments: Stripe, YooKassa, Smart Glocal, Tranzzo and others. ShopGram auto-detects the provider from the token prefix.
- Provider token (live) — paste the live token BotFather gives you.
- Provider token (test) — optional test-mode token for sandbox runs.
- Test mode — when on, the test token is used for invoices regardless of order context.
- Shipping callback — opt-in. When on, the gateway sends
is_flexible=trueon each invoice and computes shipping live via WooCommerce.
Telegram Stars
For virtual or downloadable products only (Telegram restriction). The Stars gateway gates on is_virtual && is_downloadable for every cart line and exposes itself in the Mini App checkout. Refunds issued in WooCommerce automatically call refundStarPayment.
- Stars per currency unit — exchange rate. The default is 1 Star = 0.013 USD (Telegram's posted rate); adjust if you sell in a currency Telegram doesn't quote.
Security model. Every invoice carries a payload sg_order:<id>:<nonce> where the nonce is wp_hash(order_id) truncated to 16 hex chars. The successful_payment webhook verifies the nonce before marking the order paid — tampered order IDs can't slip through.
Refunds
- Card — Bot API does not expose card refunds. Issue refunds in your provider dashboard (Stripe etc.); the WC order status doesn't auto-update.
- Stars — Handled automatically through
refundStarPaymentwhen the WC order is refunded.
Site Chat
A floating chat bubble for your website. Every visitor conversation becomes a topic inside the connected Telegram supergroup, so your team replies from the Telegram app they already use.
General
- Status — master on/off. Hides the bubble in the WP-admin preview and inside the Mini App regardless of other settings.
- Appearance — primary color, bottom-right vs. bottom-left, header title and subtitle, input placeholder.
- Where to show — hide on the home page, by post type, or by exact post/page IDs.
- Proactive greeting — auto-open the bubble with a message after N seconds. Fires once per visitor (24h cookie-bound) and skips returning visitors who already have an active chat.
- Visitor notifications — play a chime when an agent replies, and (optionally) prompt the visitor to allow native desktop notifications.
Pre-chat form
Add fields like Name, Email, Subject, or a free-text question. Each field has its own enabled/required toggles. The submitted values are shown as the first message in the visitor's topic so the agent sees who they're talking to before the actual question lands.
Working hours
Outside working hours the widget shows the offline message and (if enabled) an email form that mirrors the visitor's question into the same Telegram topic. Inside working hours the form is hidden and the chat behaves normally.
AI Assistant
Mode
- Bot only — AI handles everything, no human hand-off.
- Bot + human hand-off — visitor sees a "Talk to a human" button. Clicking it flips the topic to
pendingand notifies your team. During offline hours the same button switches to "Email us" and posts the question into the topic.
OpenAI
- API key — stored in
wp_options. Get one at platform.openai.com. - Model — default is
gpt-4o-mini(cheap, fast). Swap forgpt-4oif you need better tool-following on long pages. - Daily reply limit — caps automated replies per visitor per day to keep spend predictable. Set
0for unlimited.
Knowledge base
Pick which pages, posts and WooCommerce products the AI is allowed to cite. ShopGram embeds the selected content at request time and constrains the model to only answer from that context — no hallucinated stock or invented prices.
Token usage. Each reply pulls the active context into the prompt. The "Knowledge base" panel shows token spend per period; pick selectively when you have hundreds of pages.
Diagnostics
The Test AI button runs a one-line ping through the live model with your saved key + system prompt. Useful for verifying the wiring without waiting for a visitor to ask something.
Troubleshooting
Webhook returns 403 — "Bad secret"
The secret stored in WP doesn't match the one Telegram is sending. Open Telegram Connection, click Re-register webhook. Some hosts strip non-standard headers — if you're behind a custom proxy, make sure X-Telegram-Bot-Api-Secret-Token passes through.
Mini App opens but says "Open via Telegram"
The app receives no initData — usually because the URL was tapped from outside Telegram. Reply-keyboard web_app buttons do not deliver initData on any official client; only inline-keyboard web_app buttons do. Use the welcome message's inline shortcuts or a Direct Link Mini App (t.me/<bot>/<short>).
Order status doesn't update after a card payment
Telegram Payments (card) refunds are not exposed via the Bot API; the WC order is paid via the successful_payment webhook on capture. If the webhook isn't reaching your site, click Re-register webhook and check the Telegram → app connectivity (proxy if needed).
Chat widget doesn't show
Check the Site Chat Status toggle is on, then the Where to show filter — by default the widget is hidden on the home page. Also confirm a Telegram supergroup is connected: the chat module bails out silently when there's no connection because there'd be nowhere to put the topic.
AI replies are empty or generic
The knowledge base is probably empty. Open Site Chat → AI Assistant → Knowledge base and tick the pages/products you want the model to cite. Without context the model has nothing site-specific to ground on and falls back to general answers.
Privacy & data
ShopGram talks to Telegram Bot API (always) and OpenAI Chat Completions API (only when the AI Assistant is enabled). Nothing is sent to ShopGram's servers — there are none.
What's stored where
- Chat messages:
{prefix}shopgram_chat_messages - Threads:
{prefix}shopgram_chat_threads - Visitors:
{prefix}shopgram_chat_users - Settings:
shopgram_settings(singlewp_optionsrow) - File uploads: streamed directly to Telegram, not written to disk on your server.
Uninstall
Activating the included uninstall.php removes every plugin table, the settings row, all post-meta keys ShopGram adds, and the cron events it schedules. Telegram-side webhooks are left in place because they belong to the bot, not the site.