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} #

The identifier you pass to the SDK.
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. If you pass none, {ymid} is an empty string. The SDK does not use the Telegram user ID as ymid. The Telegram user ID arrives separately as {telegram_id}. The impression and click of the same ad show arrive with the same ymid. Retries of a postback also repeat it. Grant one reward per ymid. Monetag inserts ymid into your URL without URL-encoding. Use only letters, digits, -, _ and .. Always use a unique ymid per ad show.

{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 zone that produced the event. It can be different from zone_id if you’re using multiple formats within the same Telegram Mini App:

• Rewarded Interstitial: the main zone.
• In-App Interstitial: the In-App zone.
• Rewarded Popup: the popup zone for impression. A click from Rewarded Popup, if it comes, has the ID of a zone linked to the popup zone.

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 to configure multiple postback endpoints per zone. One Telegram Mini App = One SDK zone = One Postback setup.

{request_var} #

The placement identifier you pass to the 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.

The value depends on the format:

• Rewarded Interstitial: as you passed it (shop_button).
• Rewarded Popup: prefixed with the main zone ID, <main zone ID>_<requestVar>. For example, with main zone 123456, requestVar: 'daily_popup' arrives as 123456_daily_popup.
• In-App Interstitial: always auto. A requestVar passed in the setup call does not reach the postback.

Monetag inserts request_var into your URL without URL-encoding. Use only letters, digits, -, _ and . in requestVar.

{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.
• If Telegram doesn’t expose the ID in the current session, the value is an empty string, never null.

{event_type} #

Possible values:

• impression: the ad was rendered and visible to the user. Sent for all three formats.
• click: the user clicked the ad. Sent for Rewarded Interstitial. Rewarded Popup can also send it, from a zone linked to the popup zone. Not sent for In-App Interstitial.

{reward_event_type} #

Indicates whether the event was monetized:

• valued: the event is monetized, and the publisher will be paid
• non_valued: no payout (for example fraud or fallback traffic)

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

{estimated_price} #

Estimated earnings for this single event, in USD. It is a decimal with 7 digits after the point, for example 0.0037000. It is not a CPM.

• It is 0.0000000 for non_valued events
• Use this for analytics, payout scaling, or performance dashboards

Example:

0.0037000 -> about $0.0037 for this event

Example Postback URL #

https://yourdomain.com/postback? ymid={ymid} &event_type={event_type} &reward_event_type={reward_event_type} &zone_id={zone_id} &sub_zone_id={sub_zone_id} &estimated_price={estimated_price} &request_var={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). Use only letters, digits, -, _ and .
• ✅ 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 an empty value (the parameter arrives as an empty string, never as null)
• ✅ Use sub_zone_id to distinguish ad formats if you use multiple formats in a single Telegram Mini App