Macro Reference #

This section provides a complete list of all macros supported in Monetag’s rewarded postback system.

Macros are special placeholders you can use in your postback URL. At runtime, Monetag automatically replaces them with actual values from the confirmed ad event.

Supported Macros #

Detailed Descriptions #

{ymid} #

A unique string or numeric identifier for the ad event.
You set it in the SDK when showing an ad:

show_XXX({ ymid: 'user123_ad_5' })

Use this to link frontend actions with postback responses. Always use a unique ymid per event.

{zone_id} #

Your main Monetag zone ID — the one passed to the SDK during initialization:

<script src="..." data-zone="123456" data-sdk="show_123456"></script>

Use this to distinguish between monetized apps or SDK.

{sub_zone_id} #

Identifies the actual zone that served the ad. This can be different from zone_id if you’re using multiple formats (e.g. Rewarded Interstitial and Rewarded Popup) within the same Telegram Mini App.

• When two ad formats are active (e.g. Interstitial and Popup), both linked to the same app, the sub_zone_id tells you which format triggered the postback.
• This allows you to use a single postback URL for the entire app, and distinguish ad formats dynamically via macros.

📌 Note: You do not need (and actually it’s impossible) to configure multiple postback endpoints per zone. One Telegram Mini App = One SDK zone = One Postback setup.

{request_var} #

Custom placement identifier sent via SDK:

show_XXX({ requestVar: 'shop_button' })

Use this to track which UI element or context triggered the ad. Common values: level_3_reward, main_banner, video_end_button, etc.

{telegram_id} #

Telegram user ID automatically extracted from the Telegram WebApp SDK.

• You do not need to set it manually.
• Our SDK will include it if available.
• This value may be empty if Telegram doesn’t expose the ID in the current session.

{event_type} #

Possible values:

• impression — the ad was rendered and visible to the user
• click — the user clicked the ad (only for Rewarded Interstitial)

{reward_event_type} #

Indicates whether the event was monetized:

• valued — the event is monetized, and the publisher will be paid
• not_valued — no payout (e.g. fallback traffic, invalid session, fraud)

Use this macro to control reward logic or discard unpaid events in your backend.

{estimated_price} #

A decimal value representing approximate revenue in USD.

• Comes from real-time bid data (CPM, CPC)
• Can be zero for unpaid or filtered events
• Use this for analytics, payout scaling, or performance dashboards

Example:

0.003700 → ~$0.0037 earned

Example Postback URL #

https://yourdomain.com/postback? ymid={ymid} &event={event_type} &value={reward_event_type} &zone={zone_id} &sub={sub_zone_id} &price={estimated_price} &source={request_var} &telegram_id={telegram_id}

Monetag will automatically replace each macro with a real value before sending the postback.

Recommendations

• ✅ Use structured values in request_var (e.g. home_top_button)
• ✅ Validate all macro values on your server
• ✅ Use ymid and reward_event_type to control rewards and prevent duplication
• ❌ Don’t assume telegram_id is always present — always check for null or empty
• ✅ Use sub_zone_id to distinguish ad formats if you use multiple formats in a single Telegram Mini App