tgm4market Plugin: Integrating a Cotonti Store with Telegram

Complete Guide to Installation, Setup, and Usage

Author: webitproff
Repository: https://github.com/webitproff/telegram-market-cotonti

Table of Contents

1. Introduction
2. Key Features
3. Architecture & File Structure
4. Plugin Installation
5. Telegram Setup
6. Configuring the Plugin via the Cotonti Admin Panel
7. Placing Tags in Templates
8. How the Plugin Works: Adding, Editing, and Deleting Products
9. Discussion Widget on the Product Page
10. Storing Settings and Data
11. Step-by-Step Usage Guide
12. Repository & Support
13. Conclusion

Introduction

tgm4market is a plugin for the Cotonti CMF, designed to fully integrate an online store (the Market module) with the Telegram messenger. It automatically publishes information about new and updated products to your Telegram channel and embeds the official Telegram discussion widget on each product page. This way, your subscribers instantly learn about new arrivals, and site visitors can view and leave comments (via Telegram) directly from the product card.

The plugin eliminates manual posting and on‑site comment moderation: everything happens automatically, while discussions remain in the familiar Telegram environment.

Key Features

• Automatic publication when a new product is created: a message with the product name and a link to the site page is sent to the Telegram channel.
• Flexible editing options when a product is modified: you can choose to create a new post, update the existing one, or do nothing.
• Official Telegram discussion widget is embedded on the product page through a dedicated tag. Comments to the channel post are shown right on the website.
• Link removal when a product is deleted: the record mapping the product to the Telegram message is removed from the database (the message itself stays in the channel).
• Separate configuration through a user‑friendly admin panel: the bot token and channel details are stored in a dedicated database table, not hard‑coded.
• Russian and English language support in the plugin interface.
• Security: built‑in input sanitization, using htmlspecialchars to prevent XSS attacks.

Architecture & File Structure

The plugin consists of several hook files that attach to Market module events and extend its functionality. Settings are kept in a separate database table, while the administrative interface is implemented as a tool in the «Tools» section.

Plugin folder structure (plugins/tgm4market/):

tgm4market/
├── tgm4market.setup.php          // Plugin header and registration
├── tgm4market.admin.php          // Settings page controller
├── tgm4market.admin.tpl          // Settings form template
├── tgm4market.global.php         // Global hook file (loads language)
├── tgm4market.market.add.add.done.php   // After‑add product hook handler
├── tgm4market.market.add.tags.php       // Tags hook: adds radio buttons to the add form
├── tgm4market.market.edit.update.done.php // After‑update product hook handler
├── tgm4market.market.edit.delete.done.php // After‑delete product hook handler
├── tgm4market.market.edit.tags.php      // Tags hook: adds radio buttons to the edit form
├── tgm4market.market.tags.php           // Tags hook: generates the discussion widget on the product page
├── inc/
│   └── tgm4market.functions.php         // Core functions: sending/editing messages, fetching configuration
├── lang/
│   ├── tgm4market.ru.lang.php           // Russian language file
│   └── tgm4market.en.lang.php           // English language file
└── setup/
    ├── tgm4market.install.sql           // SQL queries on installation
    └── tgm4market.uninstall.sql         // SQL queries on uninstall

Each file handles a specific part of the logic, making maintenance and customization straightforward.

Plugin Installation

1. Copy the tgm4market folder into the plugins/ directory of your Cotonti website.
2. Go to the admin panel, navigate to «Extensions» → «Plugins».
3. Find tgm4market in the list and click «Install».
   • During installation, the following database tables are created automatically:
     • cot_tgm4market — stores the mapping «product ID – Telegram message ID».
     • cot_tgm4market_cfg — stores settings: bot token and channel usernames.
4. After a successful installation, the plugin becomes active, and you can proceed to configure it.

Telegram Setup

The plugin requires three entities in Telegram:

• A bot — will publish messages to the channel.
• A public channel — where the bot will post.
• A discussion group — comments will take place in a separate group linked to the channel.

Quick guide:

1. Create a bot via @BotFather. Run the /newbot command, give it a name and a username ending in bot (e.g., myshop_bot). Save the token you receive — you'll need it for plugin configuration.
2. Create a public channel. When creating, be sure to choose «Public channel» and set a username (e.g., myshop). The channel address will be t.me/myshop. This username will be used in two forms:
   • with the @ symbol (@myshop) — for sending messages via the bot,
   • without the @ symbol (myshop) — for the discussion widget.
3. Create a discussion group (any group, can be private). Open the channel you just created, go to Settings → «Discussion» → «Add a group», and select the group.
4. Add the bot to both the channel and the group as an administrator. In the channel, make sure to grant the «Post messages» right. In the group, read access is sufficient.

A detailed step‑by‑step guide with screenshots is available in the plugin documentation in the repository.

Configuring the Plugin via the Cotonti Admin Panel

After installation, go to «Tools» in the Cotonti admin panel and choose tgm4market. A settings page will open at:
admin.php?m=other&p=tgm4market

The form has three fields:

• Channel username (without @, for the widget)
  Enter the username of your public channel without the @ symbol. Example: myshop.
  This value is used to build the HTML discussion widget on the product page.
• @Channel username (for sending messages)
  Enter the same username, but with the @ symbol. Example: @myshop.
  This value is used when sending messages via the Telegram API (the bot will publish posts to this channel).
• Bot token
  Paste the token you got from @BotFather. It looks like 123456789:ABCdef....

Click «Save». All data will be written to the cot_tgm4market_cfg table with cfg_id = 1. The next time you open the settings page, the values will be loaded automatically from the database.

These settings can be changed at any time. The plugin does not store them in Cotonti configuration files, making site migration safer.

Placing Tags in Templates

For the plugin to work, you need to insert special tags into your Cotonti theme (skin) templates. All tags are generated by the plugin automatically when the necessary settings are present.

1. Tag for the Add Product Form

File: skins/your_skin/market.add.tpl
Tag: {TGM4MARKET_ADD_ACTION}

Place it in a convenient spot (e.g., before the «Save» button). It will add a block with radio buttons:

• «Do nothing»
• «Publish as new»

By default, when creating a new product, «Publish as new» is selected — meaning the message will be sent to the channel immediately. You can switch to «Do nothing» to skip publication.

2. Tag for the Edit Product Form

File: skins/your_skin/market.edit.tpl
Tag: {TGM4MARKET_EDIT_ACTION}

It adds three radio buttons:

• «Do nothing»
• «Publish as new»
• «Update existing»

«Do nothing» is pre‑selected by default to avoid accidentally changing a Telegram post. The chosen action affects behavior when product changes are saved (see below).

3. Tag for the Discussion Widget

File: skins/your_skin/market.tpl (main product page template)
Tag: {TGM4MARKET_DISCUSSION}

Insert it where you want the discussion block to appear. Usually this is after the product description or in a separate tab. The plugin will automatically load the official Telegram widget script with the correct post ID.

Important: All tags are processed only when the plugin is active and the settings are correctly filled. If settings are missing or the plugin is disabled, the tags produce no output.

How the Plugin Works: Adding, Editing, and Deleting Products

Adding a Product

1. When creating a product, the admin can choose an action via radio buttons. If «Do nothing» is selected, the plugin stops.
2. If «Publish as new» is selected (the default), after the product is successfully saved, the tgm4market_send_message() function is called. It builds the message text:
   • A prefix (e.g., «🆕 New product:») is taken from the language file.
   • The product name is escaped for security (htmlspecialchars); note that in the current version a simple string interpolation is used because line breaks weren't working in HTML mode — using a version with \n and http_build_query is recommended.
   • The absolute URL to the product page is generated.
3. The function sends a request to the Telegram Bot API using the sendMessage method, with the channel's @username and the bot token from settings. Telegram returns a unique message_id.
4. The plugin stores a record in the cot_tgm4market table containing item_id (product ID) and message_id.

Editing a Product

When editing, the admin chooses one of three actions:

• Do nothing — the plugin performs no Telegram operations.
• Publish as new — a new message is sent to the channel (similar to adding), and the old link is updated: if a record already exists, the message_id is replaced; otherwise, a new one is created.
• Update existing — if a record exists for this product, the editMessageText API method is called, changing the text of the previously published message. This is useful for correcting a product description without creating a new post.

Deleting a Product

When a product is deleted (moved to trash or permanently removed), the plugin simply deletes the record from cot_tgm4market, breaking the link. The Telegram post itself remains — thus the publication history is preserved.

Discussion Widget on the Product Page

The plugin uses the official Telegram discussion widget. It is embedded via the {TGM4MARKET_DISCUSSION} tag and shows the comment thread for a specific channel post.

How it works:

• When the product page is opened, the plugin looks up the item_id in the cot_tgm4market table.
• It retrieves the message_id.
• It reads the chat_id_market (channel username without @) from the settings.

• It generates the following HTML:

  <script async src="https://telegram.org/js/telegram-widget.js?22"
          data-telegram-discussion="myshop/12345"
          data-comments-limit="5">
  </script>
  

• This script automatically loads and displays comments from the group linked to the channel.

This way, visitors can see the discussion and leave comments by opening the conversation in Telegram (by clicking the «Comment» button on the site or directly in the app).

Storing Settings and Data

The plugin uses two database tables in Cotonti:

1. cot_tgm4market_cfg — Configuration

Structure:

• cfg_id — primary key (always 1, a single record).
• chat_id_market — channel username without @ (for the widget).
• chat_id_edit — channel username with @ (for the API).
• bot_token — Telegram bot token.

Configuration data is accessed through the tgm4market_get_cfg() function, which runs:
SELECT * FROM {$db_x}tgm4market_cfg WHERE cfg_id = 1

Every file that needs settings calls this function and extracts the required field from the resulting array. This means no tokens or channel names are hard‑coded — everything is loaded dynamically from the database.

2. cot_tgm4market — Product–Message Links

Structure:

• item_id (int, unique) — product ID in the Market module.
• message_id (int) — Telegram message identifier.

Used to keep the mapping of «which product belongs to which channel post». When building the widget or updating a post, the plugin refers to this table.

Step-by-Step Usage Guide

Assuming you have already installed the plugin and set up Telegram as described above.

1. Fill in the plugin settings
   Go to admin.php?m=other&p=tgm4market, enter myshop in the first field, @myshop in the second, and the bot token. Click «Save».
2. Add tags to templates
   • In market.add.tpl, insert {TGM4MARKET_ADD_ACTION}.
   • In market.edit.tpl, insert {TGM4MARKET_EDIT_ACTION}.
   • In market.tpl, insert {TGM4MARKET_DISCUSSION} where you want the discussion to appear.
3. Create a new product
   Go to the Add Product page. A panel with an action choice will appear. By default, «Publish as new» is selected. Fill in the fields and save.
   Check your Telegram channel: a message with the product name and a link should appear.
4. Open the product page on the site
   You'll see the discussion widget. If the comment group is empty, it will show «No messages yet». Now your subscribers can comment, and the comments will be displayed on the site.
5. Edit a product
   When editing, a block with three options appears. You can update the existing post or publish a new one. Choose the desired action and save the changes.
6. Delete a product
   When a product is deleted, the link to the post is removed from the database, but the post itself stays in the channel (you can delete it manually if necessary).

Repository & Support

The plugin is fully open‑source and available for download on GitHub:
https://github.com/webitproff/telegram-market-cotonti

There you'll also find the latest release archive and the ability to report bugs or suggest improvements through Issues. The plugin is distributed under the BSD license.

Conclusion

tgm4market is a powerful and flexible tool for automating the interaction between your Cotonti‑based online store and Telegram. It saves the admin time, increases audience engagement, and makes product discussions lively and accessible right on the website. Thanks to its thoughtful architecture and simple setup, the plugin suits both small and large projects.

If you have any questions or would like to propose an enhancement, feel free to reach out via Issues on GitHub. Wishing you successful sales and lively discussions!