Skip to content

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_TOKEN

If 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 contain imp.banner; we answer with a Native 1.2 ad (see Response Format below)
  • /v1/rtb/bid/video — the impression must contain imp.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 ​

FieldNotes
idRequest ID. Missing → 400
user.ext.telegram.id or user.idUser ID; the Telegram ID takes precedence. Missing → 204 (no-bid)
device.ipUser's IP address, used for geo-targeting. For IPv6-only traffic send device.ipv6. Missing both → 400
device.uaUser 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: adm is 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: adm is VAST XML
  • bid.mtype gives the markup type: 1 — HTML banner, 2 — video (VAST), 4 — native. Don't rely on ext.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"
      }
    }]
  }]
}
FieldDescription
idOur unique bid ID (also used in the tracking URLs)
impidimp.id from your request
priceUSD CPM we pay for an impression (first-price)
admNative 1.2 JSON (banner endpoint) or VAST XML (video endpoint)
mtypeMarkup type: 1 banner, 2 video, 4 native
cridCreative ID
adomainAdvertiser domain, when known
burlBilling notice — see Tracking & Attribution
w, hRequested slot size
ext.impurlSame URL as burl
ext.clickurlOur click tracker — fire it on every click
ext.landing_urlLanding page, same as native link.url
ext.title, ext.description, ext.cta_text, ext.img_url, ext.logo_urlCopies 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.banner on 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 as ext.impurl) is the billing event: we pay price for every impression registered on it
  • Fire it once, from the user's device, when the ad is actually rendered (the way Prebid.js fires burl on 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 burl and ext.impurl won't double-count
  • There are no price macros: ${AUCTION_PRICE} is ignored, and we pay the price we 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.clickurl from the device (fire-and-forget), then open the native link.url (same as ext.landing_url). For video, use VAST ClickThrough
  • ext.clickurl is our click counter, not optional analytics. If the impression wasn't fired, the click registers it as well
  • link.url is 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 with Telegram.WebApp.openTelegramLink(url) and other URLs with Telegram.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.country is 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 cur field)

Testing ​

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/json

Request Parameters ​

ParameterTypeRequiredDescription
feedstringYesFeed type: "banner" or "video"
startTsnumberNoUnix timestamp for start date (defaults to 7 days ago)
endTsnumberNoUnix 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: