SSP Integration Telegram Native

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": 3,
 "width": 150,
 "height": 100,
 "production": true
}

Request JSON Attributes

API Request Parameters

Parameter	Type	Required	Description
ip	String	Yes	User IP address (IPv4/IPv6 supported)
user_agent	String	Yes	User agent string
publisher_id	String	Yes	Publisher ID
language_code	String	No	User language in alpha-2 format
widget_id	String	No	Mini App ID
telegram_id	String	No	Telegram ID number
bid_floor	Double	No	Minimum bid expressed in CPC or CPM depending on SSP configuration
number_of_bids	Integer	No	Number of bids in response (default: 1 if not specified)
blocked_categories	List of integers	No	Blocked advertiser category IDs (see Appendix A)
premium	Boolean	No	Indicates if the user is premium (default: false if not specified)
motivated	Boolean	No	Indicates whether the user action was motivated or not
width	Integer	No	Width of requested creative (in pixels)
height	Integer	No	Height of requested creative (in pixels)
production	Boolean	No	Indicates production mode (default: true if not specified). Use false for test responses during integration.

Notes:

• Required parameters must be included in all requests
• When production=false, test responses will be returned for integration verification
• Default values are applied when optional parameters are omitted:
  • number_of_bids: 1
  • premium: false
  • production: true
• All parameters are case-sensitive
• Dimensions (width/height) should be specified in pixels when required

Response Sample

[
   {
      "title":"test",
      "description":"test",
"image":"https://us.boxif.xyz/nty/metrics/save.img?event=impressions&bid-id=v2-1728914821764-14-14065-1373881-17047345-5c5c-bf4e-e314-fc908803c0a4&img=https%3A%2F%2Fcdn.amnew.net%2Ffiles%2F66d6d40333b3b_2024_09_03_09_16_51_image.webp",
"image_preload":"https://cdn.amnew.net/files/66d6d40333b3b_2024_09_03_09_16_51_image.webp",
"notification_url":"https://us.boxif.xyz/nty/metrics/save?event=impressions&bid-id=v2-1728914821764-14-14065-1373881-17047345-5c5c-bf4e-e314-fc908803c0a4", "link":"https://us.boxif.xyz/nty/postback/click?key=v2-1728914821764-14-14065-1373881-17047345-5c5c-bf4e-e314-fc908803c0a4",
      "bid_price":0.0000093
   },
   {
      "title":"test",
      "description":"test",   
"image":"https://us.boxif.xyz/nty/metrics/save.img?event=impressions&bid-id=v2-1728914821764-14-14065-1373881-068d4342-f9af-e153-437b-430ef038d5b5&img=https%3A%2F%2Fcdn.amnew.net%2Ffiles%2F66d6d40333b3b_2024_09_03_09_16_51_image.webp",
"image_preload":"https://cdn.amnew.net/files/66d6d40333b3b_2024_09_03_09_16_51_image.webp",
"notification_url":"https://us.boxif.xyz/nty/metrics/save?event=impressions&bid-id=v2-1728914821764-14-14065-1373881-17047345-5c5c-bf4e-e314-fc908803c0a4",
      "link":"https://us.boxif.xyz/nty/postback/click?key=v2-1728914821764-14-14065-1373881-068d4342-f9af-e153-437b-430ef038d5b5",
      "bid_price":0.0000093
   }
]

Response JSON Attributes

Creative Response Parameters

Parameter	Type	Description
title	String	Creative Title
description	String	Creative Description
image	String	Link to creative icon
image_preload	String	Link to creative banner
notification_url	String	Notification URL for impression tracking
link	String	Click URL
bid_price	Double	Bid price expressed in CPC or CPM depending on SSP configuration

Important Notes:

• All URLs (image, image_preload, notification_url, link) must be properly encoded
• image and image_preload should point to publicly accessible resources
• notification_url will be pinged when the impression is recorded
• bid_price unit depends on SSP configuration (could be CPC or CPM)
• All fields are case-sensitive

Appendix A. Advertiser Categories

Advertiser Categories

ID	Category Name
18	Finance - Other
30	Travel
36	Nutra - Weight Loss
37	Nutra - Brain Booster
38	Nutra - Dermatology
39	Nutra - Hair loss
40	Nutra - Parasites
41	Nutra - Bones & Joints
42	Nutra - Diabetis
43	Nutra - Eye & Vision
44	Nutra - Foot Health
45	Nutra - Hemorrhoid
46	Nutra - Papilloma
47	Nutra - Psoriasis
48	Nutra - Sleep
49	Nutra - Varicosis
50	Nutra - Other
51	Gambling - Casino
52	Gambling - Betting
53	Gambling - Poker
54	Gambling - Other
55	Sweepstakes - Gift Cards Global
56	Sweepstakes - Electronics
57	Sweepstakes - Gift Cards Local
58	Sweepstakes - Other
59	Dating - Regular Mainstream
64	Dating - Other
65	E-commerce - Fashion
66	E-commerce - General Ecommerce
67	E-commerce - Shopping
68	E-commerce - Other
69	Finance - Regular trading
70	Finance - Insurance
71	Finance - Binary options
72	Finance - Credit / Debt & Loans
73	Finance - Financial Infoproducts
74	Finance - Banking
75	Finance - Crypto Trading
76	Finance - Crypto ICO
77	Games - Browser Game
78	Games - PC Game
79	Games - Google Play Game
80	Games - Other
81	Job search - Other
82	Software & Apps - Antivirus
83	Software & Apps - VPN
84	Software & Apps - Utility
85	Software & Apps - Other
86	Media - Blogs & Media
87	Media - Videos on Demand
89	Media - Other
90	Traffic Arbitrage - Search Arbitrage
91	Traffic Arbitrage - Push Subscriptions
93	Traffic Arbitrage - Other
94	Telecom - Mobile Carriers Plan
95	Telecom - Mobile Carriers Content
96	Telecom - Other
97	Other - Uncategorized
98	Other - LP N/A
99	Multiple offers - Other
100	Automotive - Other
103	Automotive - Buying/Selling Cars
104	Automotive - Car Parts
105	Business - Brand page
106	Business - Services
107	Business - Education
108	Business - Medical
109	Nutra - Blood & Blood Vessels
110	Sweepstakes - Cash reward
111	Surveys & Questionnaires
112	Finance - Investing
114	Software & Apps - Cleaners
115	Media - Local News
116	Media - Global News

Usage Notes:

• These IDs are used in the blocked_categories parameter to filter unwanted ad categories
• Multiple categories can be blocked by providing an array of these IDs
• Category names follow "Parent - Subcategory" format for better organization