HTTP APITelegram

Photos & animation

POST/api/v1/ad/fetch-image

Strict image-only endpoint. Same request shape as /api/v1/ad/fetch minus accept_formats (the server always treats it as ["image"]). Use this when you want to display a photo or animation ad separately from your LLM text reply. Returns { "has_ad": false, ... } when no image inventory is available for the platform or language.

Authentication

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Same Bearer token as /api/v1/ad. Generate keys in your publisher settings.

Request body

Field	Type	Description
`user_id`required	number	Finite numeric Telegram user ID (ctx.from.id). Telegram User docs →
`platform_id`required	string	Your platform's public ID (plt_…). platforms dashboard →
`language_code`required	string	Non-empty IETF language tag (e.g. "en", "ru"). Required even when Telegram omits language_code; use the language selected in your bot. Telegram User docs →
`is_premium`	boolean	Whether the user has Telegram Premium. Default: false. Telegram User docs →
`group_id`	number	Telegram chat ID for group/supergroup placements — frequency and daily caps then apply per-chat. Omit for 1:1 (private) chats. Telegram Chat docs →
`participants_count`	number	Non-negative member count of the group chat. Only meaningful alongside group_id.
`group_name`	string	Optional group title. Validated as a string, but currently not used by the ad routes after parsing.
`parse_mode`	string	"HTML", "MarkdownV2", or "Markdown". When set, adds a pre-formatted ad_text_formatted field (a hyperlink wrapping ad_text in the selected parse mode).
`platform`	string	Surface type. Default: "telegram".

Required fields.

Response — ad served

200 OK

{
  "has_ad": true,
  "impression_id": "imp_xxx",
  "ad": {
    "format": "image",
    "ad_text": "Try Sidekick",
    "ad_text_formatted": "<a href=\"https://sidekick-ads.com/api/v1/click/imp_xxx\">Try Sidekick</a>",
    "ad_url": "https://sidekick-ads.com/api/v1/click/imp_xxx",
    "button_text": "Try",
    "button_url": "https://sidekick-ads.com/api/v1/click/imp_xxx",
    "media_type": "photo",
    "image_url": "https://cdn.example.com/sidekick/ad.jpg",
    "image_mime": "image/jpeg"
  }
}

media_type is either "photo" or "animation" — use sendPhoto or sendAnimation accordingly. ad_text is the plain caption; ad_text_formatted wraps it in an anchor tag so the caption becomes a tappable link. button_url is the click-tracking redirect URL.

Response — no ad available

200 OK

{ "has_ad": false, "impression_id": null, "ad": null }

When no image campaign matches the platform or language, both fields are null. Fallback to a text ad via /api/v1/ad/fetch or serve the LLM reply without an ad.

Error responses

Status	Meaning
`400`	A required field is missing, a field value is invalid, or platform_id does not identify a platform owned by this account.
`401`	Invalid or missing API key.