Documentation — TeleNotify Pro

Overview

TeleNotify is an embedded Shopify app that connects a Shopify store to one or more verified Telegram chats. Its primary notification flow starts when a Shopify order is marked as paid.

Paid-order notifications

Send paid-order information to verified Telegram chats according to the active plan.

Telegram chat management

Add, test, verify, activate, disable, and remove chat destinations.

Custom templates

Pro merchants can build and preview a custom Telegram message template.

Product tools

Pro merchants can import, export, and create Shopify products through Telegram tools.

Notification event: The current production flow sends notifications for the orders/paid webhook. Order-created and order-updated events are acknowledged without sending duplicate notifications.

Merchant installation and first setup

Use these steps after the app is available to install from Shopify.

Open app listingInstall appApprove permissionsOpen embedded appConnect Telegram

Install TeleNotify

Open the TeleNotify app listing or installation link and select the option to install the app on your Shopify store.

Review Shopify permissions

Shopify shows the permissions requested by TeleNotify. Review them and approve the installation to continue.

Open the embedded dashboard

After OAuth completes, Shopify redirects the merchant to the embedded TeleNotify interface inside Shopify Admin.

Open Settings

Use the left navigation and open Settings to configure the Telegram bot and chat destination.

Telegram bot and chat setup

A Telegram bot token and at least one verified chat are required before order notifications can be delivered.

3.1 Create a Telegram bot

Open BotFather

In Telegram, search for the verified @BotFather account and open the chat.

Create the bot

Send /newbot, enter a bot display name, and then enter a unique username ending in bot.

Copy the token

BotFather returns an API token. Keep it private and paste it only into the TeleNotify Settings page.

3.2 Add and verify a Telegram chat

Add the bot to the destination

Open the target private chat, group, or channel and ensure the bot has permission to send messages.

Enable notifications

In TeleNotify → Settings, enable Telegram notifications and save the bot token.

Add the Chat ID

Enter the Telegram Chat ID and an optional display name, then save the chat.

Test the connection

Select Test. When Telegram accepts the message, TeleNotify marks the chat as verified and active.

Keep credentials private: Never place the bot token, full Chat ID, Shopify access token, or customer data in screenshots, public documentation, or the App Store listing.

Paid-order notification flow

TeleNotify sends a message only when all required eligibility checks pass.

Order is paidShopify sends webhookTeleNotify validates shop and planVerified chats selectedTelegram message sent

The Shopify shop must be active.
Telegram notifications must be enabled.
A valid bot token must be saved.
The subscription must be active.
The Free plan monthly order allowance must not be exceeded.
The destination chat must be verified and active.

4.1 Test the notification

Create a test order

Create an order in the Shopify development store using demo customer and product data.

Mark the order as paid

Complete or mark the order payment so Shopify triggers the paid-order event.

Check Telegram

Confirm that the connected verified chat receives one notification with the expected order details.

Custom message templates

Custom templates are a Pro feature. Free shops use the default paid-order template.

Open Message Template

From the embedded navigation, open Message Template.

Select Custom

Choose the Custom option to enable the rich-text editor.

Add supported variables

Insert variables from the supported-variable panel and use the live Telegram preview to check the output.

Save the template

Select Save Template, then create another paid test order to verify the delivered message.

5.1 Supported variables in the current project

{{order_number}}, {{order_id}}, {{customer_name}}, {{customer_first_name}}, {{customer_last_name}}, {{customer_email}}, {{customer_phone}}, {{line_items}}, {{total_price}}, {{currency}}, {{financial_status}}, {{fulfillment_status}}, {{shipping_address}}, {{order_note}}, {{created_at}}, {{shop_domain}}, {{product_titles}}, {{first_product_title}}, {{first_product_price}}

Only include customer fields that the merchant needs. Access to protected customer fields must match the app's approved protected customer data request and privacy disclosures.

Product management through Telegram

The current project includes Pro product tools through Telegram commands and a Telegram Mini App product form.

Command	Plan	Current purpose
`/start`	Free and Pro	Shows the welcome and help context.
`/help`	Free and Pro	Lists available bot commands.
`/export_products`	Pro	Exports Shopify products to a CSV file and sends it through Telegram.
`/import_products`	Pro	Accepts a supported CSV or plain document, imports grouped product data, and reports results.
`/new_product`	Pro	Opens product-creation actions, including the Telegram Mini App form.

6.1 Export products

Send /export_productsProducts are retrievedCSV is generatedFile is returned in Telegram

6.2 Import products

Use an exported file as the template

This helps preserve the product grouping and expected CSV structure.

Upload the document to the verified bot chat

The current implementation supports CSV/plain documents up to 15 MB.

Review the result summary

Telegram reports the created, updated, skipped, or failed product results.

6.3 Add a product

Send /new_product and open the Telegram Mini App form. The current form supports product title, description, pricing, variants, inventory, media, collections, category, tags, SEO, and product status.

Plans and Shopify billing

The current project defines a Free plan and a Pro plan. Paid charges must be approved by the merchant through a Shopify-provided billing flow.

Capability	Free	Pro
Price	USD 0/month	USD 9.99/month
Paid-order allowance	20 per month	Unlimited
Active Telegram chats	1	Multiple
Basic paid-order notifications	Yes	Yes
Custom message template	No	Yes
Product import/export commands	No	Yes
Telegram product creation	No	Yes
Support	Standard	Priority
First Pro activation trial	Not applicable	7 days when not previously used

7.1 Upgrade flow

Open PricingSelect ProApprove in ShopifyReturn to TeleNotifyPro features activate

7.2 Downgrade flow

The current project schedules a Pro-to-Free downgrade without proration. Pro access remains active until the current billing period ends. When the downgrade becomes effective, the plan changes to Free and only one active Telegram chat remains.

Shopify developer note: Shopify currently recommends Shopify App Pricing for App Store apps. If this project continues using its manual GraphQL billing flow, the merchant approval, activation, cancellation, reconciliation, test mode, and multi-store isolation must all be verified before submission.

Support and Help

Merchants can submit support requests directly from the embedded application.

Open Support & Help

Open the support form from the embedded app.

Select the issue type

Choose order, Telegram, product synchronization, billing, or another supported issue category.

Enter contact details and message

Provide a valid email and a clear description between 10 and 5,000 characters.

Submit the request

The app stores the support request and sends an email using the configured SMTP settings.

Shopify developer and App Store configuration

This section is for the app owner or developer preparing TeleNotify for public distribution.

9.1 Official dashboard links

Shopify Partner DashboardOpen your Partner account and app distribution area.Shopify Dev DashboardManage app configuration, versions, scopes, URLs, and releases.Select a distribution methodOfficial public/custom distribution guidance.Submit an app for reviewOfficial submission and review steps.

9.2 Configure and release an app version

Open the app in Dev Dashboard

Go to Apps → TeleNotify → Versions → Create version.

Set the production App URL

Use the public HTTPS embedded entry URL for the deployed application.

Add the OAuth redirect URL

The current project callback route is /auth/callback. The full URL must exactly match the released configuration.

Align scopes and webhooks

Make the Dev Dashboard/app version, shopify.app.toml, and Laravel routes use one canonical configuration.

Release the version

Configuration changes do not become active until the app version containing them is released.

9.3 Current TeleNotify route patterns

App / installation: https://YOUR-DOMAIN/ Embedded app: https://YOUR-DOMAIN/embedded OAuth callback: https://YOUR-DOMAIN/auth/callback Billing confirmation: https://YOUR-DOMAIN/api/billing/success Telegram bot webhook: https://YOUR-DOMAIN/api/telegram/bot/{shopDomain} Paid-order webhook: https://YOUR-DOMAIN/api/webhook/orders/paid Uninstall webhook: https://YOUR-DOMAIN/api/webhook/app/uninstalled

Deployment check: Replace YOUR-DOMAIN with the real HTTPS production domain. Do not publish placeholder URLs.

9.4 Privacy and compliance

Public apps must implement Shopify's required privacy webhooks. The current uploaded project does not expose these three routes in its verified route list, so they must be implemented and tested before submission.

customers/data_request customers/redact shop/redact

Privacy law complianceOfficial webhook and privacy handling requirements.App privacy requirementsPrivacy policy and personal-data guidance.

Shopify API permissions

Request only the scopes that are required by working app features. A write scope normally includes read access to the same resource, so unnecessary duplicate or broad scopes should be removed.

10.1 Scopes currently requested by the application code

read_products, write_products, read_orders, write_orders, read_customers, write_customers, read_inventory, write_inventory, read_fulfillments, write_fulfillments, read_shipping, write_shipping, read_locations

10.2 Why the current features may use these permissions

Feature	Relevant permission area
Paid-order Telegram notification	Orders; protected customer fields only when included in the configured message.
CSV product export	Products.
CSV product import and product creation	Products, inventory, and locations.
Product media and variants	Products and inventory.

Configuration mismatch found: The current shopify.app.toml declares a smaller set of scopes than the application code. Align the manifest, released app version, OAuth request, and actual feature needs before publishing.

10.3 Protected customer data

Because the current message-template variables can include customer name, email, phone, and shipping address, complete the protected customer data request in the Partner Dashboard if these fields are used. Request only the fields required by the merchant-facing functionality.

Partner DashboardApp distributionSelect appAPI access requestsProtected customer data

Protected customer dataOfficial requirements and access process.Shopify access scopesOfficial scope reference.

Shopify App Store review preparation

Complete all required sections before selecting the final Submit for review action.

11.1 Submission path

Partner DashboardApp distributionTeleNotifyDistributionManage submission

11.2 Prepare the listing

App name, subtitle, introduction, details, feature list, category, integrations, and supported languages.
App icon, feature image, and three to six accurate product screenshots.
Live privacy policy URL and support contact.
Accurate Free and Pro pricing information.
Reviewer video, test credentials, and step-by-step testing instructions.

11.3 Recommended reviewer test sequence for TeleNotify

Install on a fresh development store

Approve scopes and confirm the embedded app opens.

Connect the test Telegram bot

Add the supplied Chat ID, send the test message, and verify the active state.

Create and pay a test order

Confirm one Telegram notification and the correct Free-plan usage update.

Test the Pro flow

Approve the test subscription, edit a custom template, use multiple chats, and test product import/export and product creation.

Test support

Submit a support request and confirm the success response.

Test lifecycle behavior

Verify downgrade, uninstall, and reinstall behavior without sharing subscriptions between stores.

11.4 Official review resources

Pass app reviewOfficial guidance for permissions, testing, billing, and reviewer access.App Store requirementsReview the complete Shopify App Store requirements.Shopify app billingOfficial billing requirements and current recommended pricing approach.

Troubleshooting

Problem	Check	Action
Embedded app is blank	Frontend build output, Vite manifest, browser console, API key, HTTPS.	Build from the `frontend` directory and deploy `public/frontend`.
OAuth callback fails	Released redirect URL, HMAC, state cache, domain, production environment.	Make the Dev Dashboard URL and `/auth/callback` match exactly.
Telegram test fails	Bot token, Chat ID, bot membership, permissions.	Add the bot to the chat, correct the Chat ID, and run Test again.
Paid order sends no message	`orders/paid` webhook, shop state, plan, limit, verified chat.	Re-register the webhook and check application logs.
Duplicate Telegram message	Duplicate webhook subscriptions and shared idempotency cache.	Keep one canonical webhook registration and persistent duplicate-event protection.
Pro approval does not activate	Billing callback, Shopify subscription status, test/live mode.	Verify confirmation URL and billing reconciliation.
Product import fails	CSV headers, grouped handles, file size, locations, GraphQL user errors.	Use the exported CSV as a template and correct the first reported error.
Support form database error	`support_requests` table.	Add and run the missing migration before enabling support in production.

Frequently asked questions

The current notification flow sends a message when Shopify delivers the orders/paid webhook and all shop, plan, usage, bot, and chat checks pass.

The current Free plan allows one active verified chat. The Pro plan supports multiple verified active chats.

Yes. Pro merchants can select Custom on the Message Template page, add supported variables, view the preview, and save the template.

Yes. The current Pro tools include /export_products, /import_products, and /new_product.

Open the app in Shopify Dev Dashboard, create an app version, configure the App URL and redirect URLs, align scopes and webhooks, and release the version.

Complete the request when customer fields such as name, email, phone, or shipping address are used. Request only the fields needed by the active feature set.