# Affiliate Network -> Telegram Postback (cPanel PHP)

This package receives the macros visible in your screenshot and sends one Telegram message for each unique lead/conversion event.

## Files
- `telegram-postback.php` — public postback endpoint
- `config.php` — Telegram credentials and shared secret
- `storage/.htaccess` — blocks direct web access to event-deduplication files

## 1. Create your Telegram bot
1. Open Telegram and message `@BotFather`.
2. Send `/newbot`, follow the steps, and copy the bot token.
3. Open your new bot and press **Start**, then send it a message.
4. In a browser open:
   `https://api.telegram.org/botYOUR_BOT_TOKEN/getUpdates`
5. Find `message.chat.id` in the response. For a private chat it is usually a positive number. For a group it is often a negative number.

Keep the bot token private. Do not send it to anyone.

## 2. Upload to cPanel
1. In cPanel, open **File Manager**.
2. Open `public_html`.
3. Create a folder named `affiliate-postback`.
4. Upload this ZIP and extract it inside that folder. The endpoint should be:
   `https://YOURDOMAIN.com/affiliate-postback/telegram-postback.php`
5. Confirm that the `storage` folder is present.

If your hosting permits it, the safer arrangement is to keep `config.php` and `storage` outside `public_html` and adjust the paths in the PHP file. For a straightforward cPanel setup, this package keeps them together; the storage folder has an access-deny rule.

## 3. Configure config.php
Edit `config.php` and replace:
- `PASTE_BOT_TOKEN_HERE` with your BotFather token
- `PASTE_CHAT_ID_HERE` with your Telegram chat ID
- `REPLACE_WITH_A_LONG_RANDOM_SECRET` with a long random string (at least 32 characters)

Use the exact same secret in the network's postback URL. Do not share these values publicly.

## 4. Test the endpoint manually
Replace the domain and secret, then open a URL like this in your browser:

`https://YOURDOMAIN.com/affiliate-postback/telegram-postback.php?key=YOUR_SECRET&leadid=TEST123&affid=1001&oid=205&campid=301&cid=10&tid=TEST-TX-001&s1=manual_test&price=2.50`

Expected browser response: `OK`
Expected Telegram result: one test notification.

Open the same URL again. It should return `OK: duplicate event ignored` and should not send a second notification.

## 5. Configure the Affiliate Network
In the offer's **Testing & Tracking** tab, use this Postback URL (replace the domain, folder and secret):

`https://YOURDOMAIN.com/affiliate-postback/telegram-postback.php?key=YOUR_SECRET&leadid=#leadid#&affid=#affid#&oid=#oid#&campid=#campid#&cid=#cid#&tid=#tid#&s1=#s1#&s2=#s2#&s3=#s3#&s4=#s4#&s5=#s5#&price=#price#&udid=#udid#`

- **Postback Delay:** use `0` for immediate notification, if the network allows it.
- **Pixel HTML:** leave blank. This is a server-to-server postback, not an HTML pixel.
- **Test Link:** use the network's own internal test link if it provides one; otherwise leave it blank.
- Click **Test Offer**, then **Save** if the network test succeeds.

The macros must be supported and substituted by your network. The macro names above are copied from the screenshot you supplied. Do not add a status macro unless the network documents one. The endpoint can accept an optional plain `status` parameter, but your screenshot does not show a status token.

## 6. Important checks
- Your domain must have a working HTTPS certificate.
- PHP cURL must be enabled in cPanel (usually under **Select PHP Version** or **PHP Extensions**).
- PHP must be able to write to `storage`. If necessary, set folder permission to `750` or `755`; avoid `777`.
- This endpoint sends a message for each unique transaction ID. If the network retries the same transaction, duplicate notifications are suppressed.
- If `#tid#` is not unique per event, ask the network support team which macro is the unique conversion/transaction identifier.
- The screenshot does not show an event-status macro. Therefore this setup alerts on every postback the network sends, but cannot reliably distinguish pending/approved/rejected unless the network supplies a status parameter.
- If the network uses POST instead of GET, this endpoint accepts both.
- Do not put the Telegram bot token in the network URL. It stays in `config.php`.

## Troubleshooting
- `403 Forbidden`: secret in the URL does not exactly match `config.php`.
- `Telegram configuration is incomplete`: config values still contain placeholders.
- `PHP cURL extension is not enabled`: enable cURL in cPanel.
- `502 Telegram notification failed`: check bot token, chat ID, bot Start status, and hosting outbound HTTPS access. If `debug` is temporarily enabled in `config.php`, inspect the PHP error log, then turn debug off.
- If no notification arrives from a real conversion, ask the network whether the postback is fired for the event and whether the macros are being replaced.

## Security
Never publish `config.php`, bot token, chat ID, or secret. Rotate the bot token with BotFather if it is exposed. Use a long random postback secret and HTTPS only.
