Appearance
GigaPub RTB Integration Guide
Overview
GigaPub RTB is a programmatic demand source for Telegram ads over OpenRTB 2.5. This guide is for exchanges and SSPs that send us bid requests.
Quick Start
Endpoints
POST https://rtb-01.gigapub.tech/v1/rtb/bid/banner # Banner placements (native ads)
POST https://rtb-01.gigapub.tech/v1/rtb/bid/video # Video placements (VAST)
Content-Type: application/json
Authorization: Bearer YOUR_API_TOKENIf you can't send headers, pass the token as a query parameter: ?token=YOUR_API_TOKEN.
Endpoint Selection
/v1/rtb/bid/banner— the impression must containimp.banner; we answer with a Native 1.2 ad (see Response Format below)/v1/rtb/bid/video— the impression must containimp.video; we answer with VAST
We bid on the first impression of a request (imp[0]) only, so please send one impression per request.
Basic Request Example
json
POST /v1/rtb/bid/banner
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json
{
"id": "unique-request-id-12345",
"imp": [{
"id": "1",
"banner": {
"format": [{"w": 320, "h": 50}]
},
"bidfloor": 0.1
}],
"app": {
"bundle": "@example_bot"
},
"device": {
"ip": "188.26.199.209",
"ua": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X)"
},
"user": {
"id": "123456789",
"ext": {
"telegram": {
"id": 123456789,
"is_premium": false,
"language_code": "en"
}
}
}
}Basic Response Example
json
{
"id": "unique-request-id-12345",
"cur": "USD",
"seatbid": [{
"seat": "giga.pub",
"bid": [{
"id": "173445678901234567",
"impid": "1",
"price": 2.5,
"adm": "{\"ver\":\"1.2\",\"assets\":[...],\"link\":{\"url\":\"https://t.me/example_bot\"}}",
"mtype": 4,
"crid": "o1234",
"adomain": ["t.me"],
"burl": "https://rtb-01.gigapub.tech/v1/rtb/imp?id=173445678901234567",
"w": 320,
"h": 50
}]
}]
}Integration Requirements
1. OpenRTB 2.5 Compliance
We accept standard OpenRTB 2.5 bid requests with Telegram-specific extensions. Responses follow OpenRTB 2.5 and also carry bid.mtype from OpenRTB 2.6.
2. Required Fields
| Field | Notes |
|---|---|
id | Request ID. Missing → 400 |
user.ext.telegram.id or user.id | User ID; the Telegram ID takes precedence. Missing → 204 (no-bid) |
device.ip | User's IP address, used for geo-targeting. For IPv6-only traffic send device.ipv6. Missing both → 400 |
device.ua | User Agent string. Missing → 400 |
device.geo.country is optional: we geolocate by IP. If you send it, both ISO-3166-1 alpha-3 (as in OpenRTB 2.5) and alpha-2 work.
Requests with regs.coppa = 1 are answered with 204: we have no child-directed demand.
3. Response Format
- Banner endpoint:
admis a Native 1.2 JSON string. We don't serve HTML markup over RTB at the moment, so please send only placements that can render native ads - Video endpoint:
admis VAST XML bid.mtypegives the markup type:1— HTML banner,2— video (VAST),4— native. Don't rely onext.ad_type: it's an internal field- All prices are USD CPM, first-price, already net of our fees
Telegram-Specific Features
User Data Extension
Include Telegram user data for better targeting. user.ext.telegram.id takes precedence over user.id; is_premium and language_code are used for targeting:
json
{
"user": {
"id": "123456789",
"ext": {
"telegram": {
"id": 123456789,
"is_premium": true,
"first_name": "John",
"last_name": "Doe",
"username": "johndoe",
"language_code": "en"
}
}
}
}App Context
Specify the Telegram bot/app context, with the bot username in app.bundle:
json
{
"app": {
"id": "12345",
"name": "Hamster Kombat",
"bundle": "@hamster_kombat_bot",
"domain": "t.me"
}
}Traffic outside Telegram (for example, native Android/iOS apps) is accepted, but our demand is bought for Telegram Mini App users: direct campaigns need a Telegram user ID, and most of them promote Telegram bots, channels and mini apps. Expect little to no fill on such traffic.
Ad Formats
1. Banner Ads
Banner placements are filled with native ads (see Native Ads below):
json
{
"imp": [{
"id": "1",
"banner": {
"w": 320,
"h": 50,
"pos": 0
},
"bidfloor": 0.5
}]
}We take the slot size from banner.w/banner.h or, if they are absent, from the first entry of banner.format. The bid's w/h echo this slot size.
Supported sizes:
- 320x50 (Mobile Banner)
- 320x100 (Large Mobile Banner)
- 300x250 (Medium Rectangle)
- 320x480 (Interstitial)
2. Video Ads
VAST-compliant video advertising:
json
{
"imp": [{
"id": "1",
"video": {
"mimes": ["video/mp4"],
"minduration": 5,
"maxduration": 30,
"protocols": [2, 3, 5, 6],
"w": 640,
"h": 480,
"linearity": 1,
"skip": 1,
"skipafter": 5
},
"bidfloor": 2.0
}]
}3. Native Ads
The banner endpoint answers with native ads. imp.banner is required: an impression with only imp.native gets 204. You may send imp.native alongside imp.banner, but we don't read imp.native.request — the response always uses the fixed asset set described in Creative Rendering. Map assets by type rather than by the asset IDs of your request.
Response Handling
Successful Bid Response (200 OK)
json
{
"id": "request-id",
"cur": "USD",
"seatbid": [{
"seat": "giga.pub",
"bid": [{
"id": "bid-id",
"impid": "1",
"price": 2.5,
"adm": "{\"ver\":\"1.2\",\"assets\":[{\"id\":1,\"title\":{\"text\":\"Play Now!\"}},...],\"link\":{\"url\":\"https://t.me/example_bot\"}}",
"mtype": 4,
"crid": "o1234",
"adomain": ["t.me"],
"burl": "https://rtb-01.gigapub.tech/v1/rtb/imp?id=bid-id",
"w": 320,
"h": 50,
"ext": {
"impurl": "https://rtb-01.gigapub.tech/v1/rtb/imp?id=bid-id",
"clickurl": "https://rtb-01.gigapub.tech/v1/rtb/click?id=bid-id",
"landing_url": "https://t.me/example_bot",
"title": "Amazing Game",
"description": "Play now and win prizes!",
"cta_text": "Install"
}
}]
}]
}| Field | Description |
|---|---|
id | Our unique bid ID (also used in the tracking URLs) |
impid | imp.id from your request |
price | USD CPM we pay for an impression (first-price) |
adm | Native 1.2 JSON (banner endpoint) or VAST XML (video endpoint) |
mtype | Markup type: 1 banner, 2 video, 4 native |
crid | Creative ID |
adomain | Advertiser domain, when known |
burl | Billing notice — see Tracking & Attribution |
w, h | Requested slot size |
ext.impurl | Same URL as burl |
ext.clickurl | Our click tracker — fire it on every click |
ext.landing_url | Landing page, same as native link.url |
ext.title, ext.description, ext.cta_text, ext.img_url, ext.logo_url | Copies of the native assets, for convenience |
No Bid Response (204 No Content)
An empty response means no bid. We return it when:
- no ad matches the request
- our auction didn't finish within 350 ms
- the bid doesn't reach
imp.bidfloor - the request has no user ID
regs.coppa = 1- the impression type doesn't match the endpoint (for example, no
imp.banneron the banner endpoint)
Error Response (400 Bad Request)
json
{
"error": "Invalid request",
"details": ["User Agent is required"]
}400 is also returned for invalid JSON or a missing request id; 401 — for a missing or invalid token.
Creative Rendering
Native Ad Format (adm field)
json
{
"ver": "1.2",
"assets": [
{
"id": 1,
"title": {"text": "Game Title"}
},
{
"id": 2,
"img": {
"url": "https://example.com/image.jpg",
"w": 300,
"h": 250,
"type": 3
}
},
{
"id": 3,
"img": {
"url": "https://example.com/icon.jpg",
"w": 64,
"h": 64,
"type": 1
}
},
{
"id": 4,
"data": {
"type": 2,
"value": "Game description text"
}
},
{
"id": 5,
"data": {
"type": 12,
"value": "Install"
}
}
],
"link": {
"url": "https://t.me/example_bot"
}
}Asset types:
- Asset 1: Title
- Asset 2: Main image (img type 3)
- Asset 3: Icon/logo (img type 1)
- Asset 4: Description (data type 2)
- Asset 5: CTA button text (data type 12)
Any asset may be missing, so treat each one as optional. Image sizes, when present, are nominal — scale images to your template.
The native response contains no imptrackers, eventtrackers or link.clicktrackers: all tracking goes through burl and ext.clickurl (see Tracking & Attribution).
Video Response
For video impressions, the adm field contains VAST XML. Our impression URL is included in the VAST <Impression>, so the player firing it is enough:
xml
<VAST version="3.0">
<Ad id="12345">
<InLine>
<AdSystem>GigaPub</AdSystem>
<AdTitle>Video Ad</AdTitle>
<Impression>https://rtb-01.gigapub.tech/v1/rtb/imp?id=bid-id</Impression>
<Creatives>
<Creative>
<Linear>
<Duration>00:00:30</Duration>
<MediaFiles>
<MediaFile type="video/mp4" width="640" height="480">
https://example.com/video.mp4
</MediaFile>
</MediaFiles>
<VideoClicks>
<ClickThrough>https://landing-page.com</ClickThrough>
<ClickTracking>https://rtb-01.gigapub.tech/v1/rtb/click?id=bid-id</ClickTracking>
</VideoClicks>
</Linear>
</Creative>
</Creatives>
</InLine>
</Ad>
</VAST>Tracking & Attribution
Impression (billing event)
burl(the same URL asext.impurl) is the billing event: we paypricefor every impression registered on it- Fire it once, from the user's device, when the ad is actually rendered (the way Prebid.js fires
burlon render). Don't fire it server-side or on auction win: our demand partners verify impressions on the device, and we reconcile against their numbers - Each bid is counted once and repeated calls are ignored, so firing both
burlandext.impurlwon't double-count - There are no price macros:
${AUCTION_PRICE}is ignored, and we pay thepricewe returned - Load image assets from the original URLs — don't proxy, re-host or prefetch them: for part of our demand, loading the image is what counts as the impression
Click
- On every click, fire
ext.clickurlfrom the device (fire-and-forget), then open the nativelink.url(same asext.landing_url). For video, use VASTClickThrough ext.clickurlis our click counter, not optional analytics. If the impression wasn't fired, the click registers it as welllink.urlis often a tracking redirect: open it only on a real user click, and don't prefetch it or follow it server-side- Many landing pages are Telegram links (
t.me/...). Inside Telegram Mini Apps, open them withTelegram.WebApp.openTelegramLink(url)and other URLs withTelegram.WebApp.openLink(url)
Example Implementation
javascript
const bid = bidResponse.seatbid[0].bid[0];
const ad = JSON.parse(bid.adm); // mtype 4: Native 1.2
// When the ad is rendered on the user's device: billing notice, once
fetch(bid.burl, {method: 'GET', mode: 'no-cors', keepalive: true});
// On a real user click
function onAdClick() {
fetch(bid.ext.clickurl, {method: 'GET', mode: 'no-cors', keepalive: true});
const url = ad.link.url; // same as bid.ext.landing_url
if (url.startsWith('https://t.me/'))
Telegram.WebApp.openTelegramLink(url);
else
Telegram.WebApp.openLink(url);
}Targeting Capabilities
Geographic Targeting
- Country-level targeting based on IP geolocation
device.geo.countryis an optional hint
User Targeting
- Telegram Premium users
- Language preferences
- Platform (iOS/Android)
Contextual Targeting
- Bot/App context via
app.bundle - User interests based on bot category
Best Practices
1. Request Optimization
- Send one impression per request
- Include Telegram user data (
user.ext.telegram): it's our main targeting signal - Set bid floors in USD
2. Response Handling
- Our side answers within about 350 ms; set your timeout with network latency in mind
- Don't proxy, re-host or prefetch creative assets
- Treat 204 as a regular no-bid
3. Integration Testing
- Test with different geo locations
- Verify all creative formats render correctly
- Monitor win rates and response times
Technical Specifications
Timeouts
- Our auction budget is 350 ms; if it's exceeded, you get 204
Rate Limits
- No hard rate limits. Under load, part of the requests may be answered with 204
- Implement reasonable request pacing
Supported Currencies
- USD only (specified in
curfield)
Testing
Banner Test Request
bash
curl -X POST https://rtb-01.gigapub.tech/v1/rtb/bid/banner \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-d '{
"id": "test-request-001",
"imp": [{
"id": "1",
"banner": {"w": 320, "h": 50},
"bidfloor": 0.1
}],
"device": {
"ip": "8.8.8.8",
"ua": "Mozilla/5.0 (iPhone; CPU iPhone OS 14_0 like Mac OS X) AppleWebKit/605.1.15",
"geo": {
"country": "USA"
}
},
"user": {
"id": "123456789",
"ext": {
"telegram": {
"id": 123456789,
"is_premium": false,
"language_code": "en"
}
}
},
"app": {
"id": "123",
"bundle": "@test_bot"
}
}'Video Test Request
bash
curl -X POST https://rtb-01.gigapub.tech/v1/rtb/bid/video \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-d '{
"id": "test-video-request-001",
"imp": [{
"id": "1",
"video": {
"mimes": ["video/mp4"],
"minduration": 5,
"maxduration": 30,
"protocols": [2, 3, 5, 6],
"w": 640,
"h": 480,
"linearity": 1,
"skip": 1,
"skipafter": 5
},
"bidfloor": 1.0
}],
"device": {
"ip": "8.8.8.8",
"ua": "Mozilla/5.0 (iPhone; CPU iPhone OS 14_0 like Mac OS X) AppleWebKit/605.1.15",
"geo": {
"country": "USA"
}
},
"user": {
"id": "123456789",
"ext": {
"telegram": {
"id": 123456789,
"is_premium": false,
"language_code": "en"
}
}
},
"app": {
"id": "123",
"bundle": "@test_bot"
}
}'Statistics API
Overview
Access your RTB performance metrics through our Statistics API. Use it to reconcile impressions, clicks and income per day and country.
Endpoint
POST https://rtb-stat-api.gigapub.tech/v1/get-stat
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/jsonRequest Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| feed | string | Yes | Feed type: "banner" or "video" |
| startTs | number | No | Unix timestamp for start date (defaults to 7 days ago) |
| endTs | number | No | Unix timestamp for end date (defaults to current time) |
Request Example
json
{
"feed": "banner",
"startTs": 1737072000,
"endTs": 1737676800
}Response Example
json
{
"status": "ok",
"data": {
"rows": [
{
"day": "2025-01-17",
"countryCode": "US",
"fillRate": "85.50",
"cpm": "2.45",
"impressions": 1250,
"clicks": 45,
"income": 3.06
}
]
}
}Metrics Explained
- fillRate: Percentage of bid requests that resulted in bids (bids/requests * 100)
- cpm: Cost per thousand impressions (revenue/impressions * 1000)
- income: Total revenue in USD
Code Examples
cURL
bash
# Get banner statistics for the last 7 days
curl -X POST https://rtb-stat-api.gigapub.tech/v1/get-stat \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-d '{"feed": "banner"}'
# Get video statistics for specific date range
curl -X POST https://rtb-stat-api.gigapub.tech/v1/get-stat \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-d '{
"feed": "video",
"startTs": 1737072000,
"endTs": 1737676800
}'Node.js
javascript
const fetch = require('node-fetch');
async function getRtbStatistics(apiKey, feed, startTs = null, endTs = null) {
const body = { feed };
if (startTs) body.startTs = startTs;
if (endTs) body.endTs = endTs;
const response = await fetch('https://rtb-stat-api.gigapub.tech/v1/get-stat', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': `Bearer ${apiKey}`
},
body: JSON.stringify(body)
});
if (!response.ok) {
const error = await response.json();
throw new Error(`API Error: ${error.error}`);
}
return await response.json();
}
// Usage
(async () => {
try {
// Get banner statistics for last 7 days
const bannerStats = await getRtbStatistics('YOUR_API_TOKEN', 'banner');
console.log('Banner Statistics:', JSON.stringify(bannerStats, null, 2));
// Get video statistics for specific date range
const videoStats = await getRtbStatistics('YOUR_API_TOKEN', 'video', 1737072000, 1737676800);
console.log('Video Statistics:', JSON.stringify(videoStats, null, 2));
} catch (error) {
console.error('Error:', error.message);
}
})();Rate Limits
- Maximum 100 requests per minute per API key
- Maximum date range: 90 days per request
- Data retention: 12 months
Support & Contact
For technical support and integration assistance:
- Telegram: @gigapub_support
- Documentation: https://docs.giga.pub/rtb-api-request.html