HTTP APIConcepts

Testing

Telegram examples. Choose your platform →

Check ad selection, Telegram delivery, and callbacks separately. An ad in an API response does not confirm that Telegram delivered it.

Choose a format

text — /ad or /ad/fetch.
image — /ad/fetch with accept_formats: ["image"] or /ad/fetch-image.
response, card, consent, quiz — /ad with the required accept_formats and capabilities. Rich format parameters.

accept_formats limits eligible formats; it does not guarantee matching active inventory. A no-ad response alone does not indicate an integration error.

Test platforms

The current test-platform flag allows test campaigns without excluding ordinary inventory. It does not disable impression billing.

The HTTP flag test_rich: true rotates through active rich demo campaigns among the accepted formats. It does not cover text or image, bypass every earlier check, or guarantee an ad when demo campaigns are paused or stopped. SDK 0.8.0 does not send this flag.

Arrange the test inventory and accounting with the Sidekick team before testing against the live service. The current API has no isolated, free mode with a guaranteed format.

Verification checklist

No ad or API failure: the user receives the original reply and keyboard.
Text: links and parse_mode work, and the bot's reply is not duplicated.
Image: photo and animation are sent using the corresponding media_type.
Rich: the ad is sent after the reply; a delivery failure uses the same ad's text fallback.
Consent and quiz: check all scenes, decline, repeated taps, and answerCallbackQuery.
Impressions and clicks: allow for reporting delay; do not request another ad just to retry Telegram delivery.

Groups and ephemeral

Ephemeral is a delivery mode, not an ad format. For an initial rich scene, pass group_id and bot_is_admin, then add receiver_user_id when sending. SDK 0.8.0 does not send group_id, so use HTTP for group-aware requests.

Delivery and callback examples · /ad/interact