SSP Integration Telegram Interstitial Video

Request Telegram integration is implemented with a POST request containing a JSON object in its body.

POST http://{ssp_id}.xml.adx1.com/telegram-bid

The Simplest Request Body Sample

{
 "ip": "192.112.192.11",
 "user_agent":"Mozilla/5.0 (Linux, Android 14; K) AppleWebKit/537.36 (KHTML, lke Gecko) Chrome/129.0.6668.81 Mobile Safari/537.36 Telegram-Android/11.2.0 (Google Pixel 6; Android 14; SDK 34; HIGH)",
 "publisher_id":"792361"
}

Full Request Body Sample

{
 "ip": "192.112.192.11",
 "user_agent":"Mozilla/5.0 (Linux, Android 14; K) AppleWebKit/537.36 (KHTML, lke Gecko) Chrome/129.0.6668.81 Mobile Safari/537.36 Telegram-Android/11.2.0 (Google Pixel 6; Android 14; SDK 34; HIGH)",
 "publisher_id":"792361",
 "widget_id":"351352",
 "bid_floor":0.0001,
 "premium": true,
 "motivated": true,
 "language_code":"en",
 "telegram_id": "515279737",
 "blocked_categories": [18, 30],
 "number_of_bids": 1,
 "production": true
}

Request JSON Attributes

API Request Specification

Core Parameters

Parameter	Type	Required	Description
ip	String	Yes	User's IP address (supports both IPv4 and IPv6 formats)
user_agent	String	Yes	Full HTTP user agent string from the client's device/browser
publisher_id	String	Yes	Unique identifier for the publisher account

Optional Parameters

Parameter	Type	Default	Description
language_code	String	-	ISO 639-1 2-letter language code
widget_id	String	-	Identifier for the Mini App integration
telegram_id	String	-	User's unique Telegram identifier
bid_floor	Double	-	Minimum acceptable bid (value in either CPC or CPM based on SSP settings)
number_of_bids	Integer	1	Desired number of bid responses (1-5 supported)
blocked_categories	Integer[]	-	List of advertiser category IDs to exclude
premium	Boolean	false	Indicates premium user status
motivated	Boolean	-	Flags if the user action was intentional
production	Boolean	true	Set to false for test mode (returns sample responses)

Default Behavior

• Testing: When production=false, the system:

  • Returns test creatives with "TEST" watermark
  • Ignores bid_floor parameter
  • Doesn't record impressions for billing

• Empty Values: Unspecified parameters will:

  • Use documented default values
  • Be treated as no restrictions (for array/object parameters)

Example Requests

Minimal Request

{
  "ip": "203.0.113.45",
  "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)",
  "publisher_id": "pub_12345"
}

Response Sample

[
    {
        "title": "test",
        "message": "test",
        "video": "https://cdn.amnew.net/files/creative-test/67c96be1dcb77_2025_03_06_09_33_21_video.mp4",
        "icon": "https://eu.skated.co/nty/metrics/save.img?event=impressions&bid-id=v2-1741608132064-14-14802-1428709-044f1744-6b2f-a571-de58-5b3678d4cfd0&img=https%3A%2F%2Fcdn.amnew.net%2Ffiles%2F671968511ff7f_2024_10_23_09_19_13_image.webp",
        "notification_url": "https://eu.skated.co/nty/metrics/save?event=impressions&bid-id=v2-1741608132064-14-14802-1428709-044f1744-6b2f-a571-de58-5b3678d4cfd0",
        "link": "https://eu.skated.co/nty/postback/click?key=v2-1741608132064-14-14802-1428709-044f1744-6b2f-a571-de58-5b3678d4cfd0",
        "button": "test",
        "bid_price": 0.31
    }
]

Response JSON Attributes

Creative Response Parameters

Parameter	Type	Description
title	String	Main headline/text displayed to the user
message	String	Supporting description text
button	String	Action button text (e.g., "Learn More", "Sign Up")
video	String	URL to video creative (MP4/HLS recommended)
icon	String	URL to square icon/image (JPG/PNG, min 300×300)
link	String	Destination URL when user interacts
notification_url	String	Impression tracking pixel URL
bid_price	Double	Winning bid value (CPC/CPM based on auction)

Implementation Guidelines

1. Media Requirements:

   • Videos: Max 30s duration, 16:9 aspect ratio preferred
   • Icons: Square format (1:1), transparent background supported

2. Tracking Rules:

   // Use EITHER icon OR notification_url for impressions
   if (response.icon) {
     // Load icon image to track impression
     new Image().src = response.icon;
   } else if (response.notification_url) {
     // Call notification URL
     fetch(response.notification_url);
   }