AI Setup Assistant

This section is for AI agents and developers using AI tools to set up and run Telegram Shopping. If you're pointing Claude, GPT, or another assistant at this extension — start here.

What's here

Page	For whom
Agent Guide	AI agents integrating with the API — full reference, every endpoint, every field
Integration Prompt	Developers who want a copy-paste system prompt, Python client, and cURL examples

Quick context

Paste this into a conversation with your AI:

Telegram Shopping is an LNbits extension that runs a Lightning-powered storefront inside Telegram. Customers shop through a Telegram Mini App (TMA) — an embedded web UI inside Telegram — browsing products, adding to cart, and paying Lightning invoices without leaving the chat. Products come from the LNbits Inventory extension. The admin manages everything through REST endpoints authenticated with LNbits wallet keys.

Three layers:

• Telegram bot — customer-facing: /start command opens the Mini App, sends order confirmations, fulfillment updates, return notifications
• Telegram Mini App (TMA) — customer-facing: product grid with categories, cart, checkout, order history, returns, messaging, inline product sharing
• REST API — admin-facing: shop CRUD, order management, fulfillment tracking, messaging, returns/refunds, marketing campaigns, statistics

An AI agent interacts with the REST API to set up shops, manage daily operations, or run an entire store autonomously.

Two modes of AI operation

Option A: Bot runs the shop, AI manages it

The Telegram bot and Mini App handle customer interactions automatically. Your AI agent uses the REST API for admin tasks — checking orders, replying to messages, approving returns, running campaigns, tracking analytics.

This is the typical setup. The bot does the selling, the AI does the managing.

Option B: AI builds and runs a complete store

An AI agent can set up an entire store from scratch through the API:

1. Validate a Telegram bot token
2. Fetch the user's Inventory ID
3. Create a shop with configuration (currency, checkout mode, shipping, returns)
4. Start the bot
5. Configure marketing campaigns
6. Monitor orders, respond to messages, manage fulfillment
7. Handle returns and refunds
8. Run promotional broadcasts

The Integration Prompt has a ready-made system prompt covering the full lifecycle.

Giving your AI access

The API uses LNbits wallet keys:

• Admin key — full access: create shops, update fulfillment, approve returns, send messages, manage campaigns, broadcast
• Invoice key — read access: list shops, orders, messages, returns, customers, statistics, campaigns

Pass the key as X-API-KEY header. Your AI needs:

1. The LNbits base URL (e.g. https://your-lnbits.com)
2. A wallet's admin key (for write operations)
3. The same wallet's invoice key (for read operations)

What an AI can do

Task	Key endpoints	Auth
Setup	Test token, fetch inventory sources, create shop, start bot	Admin
Daily ops	List orders, update fulfillment, check unread count, reply to messages	Admin
Returns	List return requests, approve (credit or Lightning), deny with reason	Admin
Campaigns	List/create/update campaigns, broadcast promotions, view send logs	Admin
Monitoring	Shop statistics (orders, revenue, customers), unread messages	Invoice
Customer data	List customers, view activity timestamps	Invoice

Questions your AI should ask the human

Before setting up a store, your AI should gather these details:

Question	Why it matters
What is your LNbits URL?	Base URL for all API calls
What is your LNbits wallet admin key?	Authentication for write operations
What is your Telegram bot token?	From @BotFather — required to run the shop
What currency do you want to use?	sat, USD, EUR, etc. — sets pricing display
What checkout info do you need?	none (anonymous), email, or address (full shipping address)
Do you want order tracking?	Enables preparing/shipping/delivered status updates
Do you want to allow returns?	Enables the return/refund flow
How long should the return window be?	Hours after purchase (default: 720 = 30 days)
Do you have shipping rates?	Flat rate, free threshold, per-kg rate
Do you want an admin chat ID for notifications?	Your personal Telegram chat ID for order alerts

End-to-end setup flow

1. POST /shop/test-token       — validate the Telegram bot token
2. GET  /sources/inventory      — find the user's Inventory extension ID
3. POST /shop                   — create the shop with all settings
4. POST /shop/{id}/start        — enable and start the bot
5. GET  /stats                  — verify it's running (check shops_live count)
6. GET  /commercial?shop_id={id} — review the 4 default campaigns
7. PUT  /commercial/{id}        — customize and enable campaigns

Daily management loop:

1. GET  /message/unread-count?shop_id={id}  — check for new messages
2. GET  /order?shop_id={id}&status=paid     — check for new orders
3. PUT  /order/{id}/fulfillment             — update shipping status
4. GET  /return?shop_id={id}&status=requested — check for return requests
5. PUT  /return/{id}/approve or /deny       — handle returns
6. POST /message/{shop_id}                  — reply to customers
7. GET  /stats                              — daily metrics

Discovery

This site serves /llms.txt following the llms.txt spec. Agents that support service discovery can find it there.