# ADSGRAM.store documentation Pilot only; no billing, payouts or Mini App SDK. ## Getting started Status: Available https://adsgram.store/docs/getting-started ### One Telegram account Use Telegram sign-in to access research, connect a channel or enter the advertising network workspace. Public documentation is readable without an account. Never send a bot token in a support message or place it in website code. ### Choose your workspace Advertisers can explore channels and creatives, then prepare a campaign draft in Network. Publishers can connect their channel for analytics or register a bot or channel for the advertising pilot. These are separate steps: channel verification does not automatically authorize advertising. ### What is live Research tools, Telegram sign-in, channel connection, website placements and the controlled network pilot are available. The pilot has no advertiser charges or publisher earnings. Read the service-status guide before planning a paid launch. ## Service availability Status: Reference https://adsgram.store/docs/service-status ### Available now Telegram sign-in; channel ownership verification; retained channel and creative research; saved shortlists; website advertising placements; administrator visit and bot-flow monitoring. The network workspace supports bot/channel campaign drafts, publisher registration, review, API keys, ad selection and pilot delivery/click reporting. ### Controlled pilot Only administrator-approved publishers can request advertisements. Only reviewed campaigns explicitly activated by an administrator can be selected. Publisher integrations must call our server API and report successful delivery. This does not automatically send Telegram messages or create income. ### Not yet released Mini App rewarded, interstitial and task SDKs; automatic channel scheduling and deletion; advertiser deposits; publisher balances and withdrawals; billed CPM/CPC campaigns; conversion postbacks; audience upload and retargeting; optimization bidding; official Telegram Ads campaign purchasing. There are no production integration instructions for these unfinished services. ### Release criteria A service becomes available after its delivery path, access controls, measured events, error recovery and operational ownership have been tested. Financial features additionally require a payment provider, ledger reconciliation, refund rules and approved commercial terms. ## Telegram sign-in Status: Available https://adsgram.store/docs/telegram-login ### Sign in Open the login page and continue with Telegram. Use @AdsGramloginbot and confirm the request associated with your browser. Return to the same browser to finish the session. ### If confirmation does not finish Restart from the login page rather than reusing an old confirmation link. Check that the bot username is correct and use the same browser tab. An approval message in Telegram alone does not prove that the website session was saved. ### Protect your account Confirm only requests you started. Administrators receive additional workspace access based on their numeric Telegram account ID. Access is checked on the server. ## How our network works Status: Pilot https://adsgram.store/docs/network-overview ### Campaign to placement An advertiser creates a bot or channel campaign, saves it as a draft and submits it. An administrator reviews the content and destination, approves it and separately activates pilot delivery. A publisher registers its platform, completes ownership review and generates a server API key after approval. ### Ad selection Approved publishers request an ad in a supported language. The API selects a random active campaign with a matching format and either that language or all languages. Campaigns belonging to the same Telegram account as the publisher are excluded. No matching campaign returns HTTP 204. ### Commercial scope This pilot does not reserve funds, charge advertisers or pay publishers. It provides a working integration path for testing inventory and delivery. There is no guaranteed traffic, fill rate, conversion volume or income. ## Create a campaign Status: Pilot https://adsgram.store/docs/create-campaign ### Prepare the creative Open Network → Advertiser campaigns. Enter an internal name, select Telegram bot or Telegram channel, and enter the title, message, destination and button label. An HTTPS image URL is optional. Use a language code such as en, tr, ru, ar or zh; use all only when the creative is suitable across languages. ### Save, submit and review Save draft creates a persistent record without delivering ads. Submit for review sends it to the administrator queue. Approval and activation are separate actions. Your draft cannot approve itself. ### Change or pause Pause an active campaign to prevent new selection. To change its content, create a replacement draft and submit the replacement for review. Existing creatives are immutable in this pilot. Up to 100 campaign records are allowed per account. ## Creative formats & specifications Status: Pilot https://adsgram.store/docs/creative-formats ### Bot and channel posts The pilot uses a title, plain-text body, optional HTTPS image and one button. Title: 1–100 characters. Body: 1–700 characters. Button label: 1–32 characters. Internal name: 1–100 characters. Destinations and image links must use HTTPS and cannot embed credentials. ### Publisher rendering Display the Sponsored label clearly. Preserve the destination click URL provided by the API. Send title and body as plain text or escape them properly before applying Telegram HTML formatting. Do not treat supplied text as executable markup. ### Media limits Image URLs are stored rather than uploaded or transformed. Publishers must ensure their chosen image can be sent by Telegram. Video, task and rewarded formats are not accepted by this pilot API. ## Languages & targeting Status: Pilot https://adsgram.store/docs/targeting ### Current controls Campaigns specify bot or channel format and a language code. The publisher supplies the language of its placement. This is publisher-provided context, not a verified location or nationality. No language is inferred from a person’s name or writing system. ### Planned controls Country, category, device, frequency limits, publisher exclusions and audience segments need their own data sources and enforcement. They are not active matching rules in this release. ### Audience privacy The current ad request does not require a Telegram user ID. Do not upload lists of users to undocumented endpoints. Audience upload and retargeting have not been released. ## Statuses & moderation Status: Pilot https://adsgram.store/docs/campaign-statuses ### Campaign lifecycle Draft → Submitted → Approved → Active. Owners can submit drafts and pause their active campaigns. Administrators review, approve, activate, pause or reject. A rejected record can be resubmitted; content corrections require a replacement draft. ### Publisher lifecycle Draft → Submitted → Approved. Only an approved publisher with a valid API key can request ads. A publisher may be paused or rejected, immediately preventing new requests. Publisher approval is not a payout agreement. ### Record retention This release retains records and does not implement automatic archival or deletion. Do not assume that inactivity will delete a campaign or revoke a publisher key. ## Network reporting Status: Pilot https://adsgram.store/docs/campaign-analytics ### Three measured events Ad requests count successful creative allocations, not all HTTP requests. Confirmed deliveries count allocations for which the publisher reported a successful send. Clicked ad links count allocations with at least one valid click redirect. Repeated confirmations and repeated clicks on the same issued link do not increase these totals. ### Limits These are all-time totals across records visible to your account. Publisher confirmations are self-reported. Clicks may include automated link access and are not verified unique people. They are not billable impressions, audited traffic, conversions or revenue. ### Website placements are separate Back office website placement reports measure browser-reported visibility and clicks. Those reports are distinct from the network API delivery totals. Do not combine them as if both use the same impression definition. ## Conversion tracking Status: Planned https://adsgram.store/docs/conversion-tracking ### Current boundary The network can record ad-link clicks. It does not yet accept registrations, purchases or channel joins as attributed conversions. There is no public conversion-confirmation endpoint. ### Required implementation The conversion service needs signed click references, account-scoped credentials, idempotent event IDs, expiry and attribution windows, replay checks and a clear goal definition. Payment events must come from a trusted server. ### External trackers AppsFlyer, Adjust, AppMetrica, Keitaro and Kochava integrations are not configured for ADSGRAM.store. Listings or credentials belonging to another advertising network must not be used as ours. ## Connect your channel Status: Available https://adsgram.store/docs/connect-channel ### Connection steps Sign in with Telegram and open Connect a channel. Start @adsgramverifybot and use the channel selection flow. Add the bot as an administrator as instructed, then complete the ownership check. The service verifies your administrator role and the bot’s access. ### Permissions Basic channel verification does not require advertising permission. Publishing or deleting advertisements is a separate capability and is not enabled by connecting your channel for analytics. ### Data and coverage The first connected channel is free. Reports reflect available snapshots and observed events. Historical series and member-level coverage may be incomplete; unknown values must not be read as zero. ## Channel advertising Status: Pilot https://adsgram.store/docs/channel-monetization ### Register inventory In Network → Publisher platforms, select Telegram channel and provide its public t.me link. Submit the record. An administrator must verify ownership and the intended placement before approving it. ### Current delivery After approval, the owner may generate an API key and request channel-format creatives from their own server. The publisher is responsible for sending a clearly labelled sponsored post and confirming successful delivery. ADSGRAM does not automatically post using the verification bot. ### Scheduled monetization Posting windows, daily caps, automatic removal, view-based settlement and earnings are planned. This release offers no scheduled posting or automatic deletion guarantee and makes no publisher payout commitment. ## Bot advertising Status: Pilot https://adsgram.store/docs/bot-monetization ### Register and verify Create a Telegram bot publisher record with its public link and submit it. The review must establish control of the bot and identify exactly where an ad will appear. Your Telegram bot token is not requested by the network workspace. ### Integrate on your server Generate the publisher key after approval. Request an ad from your backend; never embed the key in browser code. Send a sponsored message only in an interaction where the user expects it, then confirm delivery after Telegram reports success. Skip HTTP 204 responses. ### Revenue All deliveries are non-billable pilot events. There is no CPC payout, reward balance or guaranteed income. Keep the bot’s core functions usable without interacting with an advertisement. ## Publisher API Status: Pilot https://adsgram.store/docs/publisher-api ### Authentication Create and submit a publisher platform, wait for approval, then generate its key in Network. Store the key only on your server. Only the owner can generate it; rotation immediately revokes the previous key. Send Authorization: Bearer with each API request. ### Request an ad GET /api/network/ad?language=en returns a creative or HTTP 204 when none matches. A publisher may request up to 60 advertisements per minute. A missing or revoked key returns 401. The format is taken from the approved publisher record, not from a query parameter. curl "https://adsgram.store/api/network/ad?language=en" \ -H "Authorization: Bearer $ADSGRAM_PUBLISHER_KEY" // HTTP 200 response fields { "campaign_id": 12, "title": "Example title", "text": "Example message", "button_text": "Open", "image_url": null, "click_url": "https://adsgram.store/api/network/click/", "delivery_token": "", "expires_in": 3600, "sponsored": true, "billing": "pilot_non_billable" } ### Confirm delivery POST /api/network/delivery after a successful Telegram send. Send JSON containing token from delivery_token and the same publisher Authorization header. Confirmations are idempotent. An expired or unrelated token returns 404. curl -X POST "https://adsgram.store/api/network/delivery" \ -H "Authorization: Bearer $ADSGRAM_PUBLISHER_KEY" \ -H "Content-Type: application/json" \ -d '{"token":""}' ### Link lifetime and failure handling Pilot click links expire one hour after allocation. Pausing a publisher or campaign also disables its redirects. Use the returned link only for an immediate pilot placement; it is unsuitable for permanent posts. Do not confirm a failed send. Avoid blind retries after a send timeout because Telegram may already have delivered the message. ## Mini App monetization Status: Planned https://adsgram.store/docs/mini-apps ### Supported format roadmap Rewarded advertisements would provide an explicitly offered in-app benefit after verified completion. Interstitials would appear at natural breaks with a usable close action. Task placements would verify a defined action before a reward is issued. These formats are not served by the current bot/channel API. ### Integration boundary There is no production ADSGRAM.store browser SDK, npm package or block ID system for Mini Apps yet. Do not install another company’s similarly named package and expect it to connect to this network. ### Release requirements The SDK needs verified app origins, Telegram launch-data validation, consent handling, accessible player controls, frequency caps, server-verified completion, replay prevention, sandbox inventory and end-to-end device testing. ## Rewards & task validation Status: Planned https://adsgram.store/docs/rewards ### Rewarded viewing A planned rewarded placement must clearly state the benefit before starting. The backend, rather than a browser callback alone, must determine whether the completion is eligible. A skipped or failed ad must not produce a reward. ### Task completion Opening a link is not sufficient proof of completing a subscription, purchase or other task. Each task type needs an authorized verification source, an eligibility rule and a single-use reward claim. ### Financial limits No cash rewards or publisher earnings are available in the current network. A test event must never be mixed into payable activity. ## Website advertising placements Status: Available https://adsgram.store/docs/website-placements ### Create a placement An administrator opens Back office and selects home-feature, workspace-top or tr-footer. Enter a title, button label, HTTPS destination, optional image and status. Each slot holds one current placement. ### Visibility Draft and paused placements do not appear publicly. Active placements appear only inside their optional UTC start/end schedule. The MessageScore homepage ad is managed through this system, independently of the network campaign queue. ### Measurement Website impressions are browser-reported when at least half the placement is visible. No minimum viewing duration is enforced in this release. Clicks and impressions can be reduced by privacy preferences, blocked requests or closed pages. These counts are not proof of paid traffic. ## Reviewing network submissions Status: Pilot https://adsgram.store/docs/moderation ### Before approving a campaign Inspect the destination and image. Confirm that the description matches the product, the destination is usable, and the advertiser can substantiate its claims. Reject deceptive content, impersonation, malicious destinations and attempts to manipulate engagement. Approval does not automatically activate delivery. ### Before approving a publisher Verify the applicant controls the listed bot or channel through an independent ownership check. Inspect the exact ad placement and confirm that sponsored content will be identified. A Telegram username alone is not proof of ownership. Do not approve an unverified platform. ### Operational controls Use the administrator view in Network to review submissions. Activation is explicitly for non-billable pilot traffic. Changes of state and API-key rotations are recorded in an audit table. Pause a record if its destination or ownership becomes questionable. No moderation turnaround time is promised. ## Payments & publisher earnings Status: Not enabled https://adsgram.store/docs/billing ### Current status The advertising network does not accept deposits or calculate payable earnings. No wallet address, minimum deposit, withdrawal threshold, fee or payout schedule has been established. A pilot counter is not a balance. ### Before commercial launch Choose a payment provider and settlement currency, define advertiser billing and publisher contracts, implement an append-only transaction ledger, reconcile provider webhooks, and test refunds, disputed events and duplicate notifications. ### Pricing page Research subscription pricing and advertising-network billing are separate products. A displayed research plan does not purchase campaign traffic. Do not transfer funds to another network expecting an ADSGRAM.store balance. ## Official Telegram Ads Status: Not connected https://adsgram.store/docs/telegram-ads ### Separate distribution system Official Telegram Ads inventory is not the same as ads posted by a channel owner or sent by a bot. ADSGRAM.store currently supports research and its own controlled publisher API pilot; it does not submit or fund official Telegram Ads campaigns. ### Requirements for a future connector A suitable account or authorized commercial integration, supported campaign operations, moderation status synchronization and budget reconciliation are required. Until these exist, no launch button or deposit request is offered for official Telegram Ads. ## Data, access & privacy Status: Reference https://adsgram.store/docs/data-and-privacy ### Account isolation Campaign and publisher records are associated with a Telegram account. Users see their own records; administrators can review the network. Publisher keys are stored as hashes and revealed only at generation. Do not share them in URLs, public logs or support screenshots. ### Research and measurement Channel research may use retained snapshots with different refresh times. Network ad requests do not require a Telegram user ID. Pilot delivery records connect a campaign and publisher to an expiring link. No conversion or earnings claim should be inferred from a click. ### Policy status This technical guide is not a privacy policy or a commercial agreement. The platform’s operator details, retention policy and formal data-request contact must be finalized before a paid advertising launch. ## Troubleshooting Status: Reference https://adsgram.store/docs/troubleshooting ### 401 or 403 Sign in again for workspace requests. For publisher API requests, verify the Authorization header, publisher approval and whether the key has been rotated. Keep bot tokens separate from publisher API keys. Workspace writes require the ADSGRAM.store origin. ### 204 — no ad No active campaign matches the publisher format and requested language, or matching campaigns belong to the publisher’s own account. Show no advertisement and continue the normal user flow. This is not a payment or technical failure. ### 404, 410, 429 or 503 404 during delivery confirmation means an unknown, expired or unrelated token. 410 on a click link means it expired or the associated record is no longer active. 429 means the request limit was reached. 503 means the service could not complete the request; retry later with bounded backoff. Never manufacture a successful impression when delivery failed. ## Glossary Status: Reference https://adsgram.store/docs/glossary ### Core entities Campaign: an advertiser’s reviewed creative and matching settings. Publisher: a bot or channel approved to request ads. Placement: the point where an ad is shown. Delivery: a publisher-confirmed successful send. ### Performance terms CTR = clicks ÷ impressions × 100, only when comparable impression and click measurements exist. CPM = spend ÷ impressions × 1,000. CPC = spend ÷ clicks. CPA = spend ÷ attributed conversions. These financial metrics are not calculated by the current non-billable pilot. ### Data limits A session is not necessarily a unique person. A delivery is not necessarily a view. A click is not a conversion. Missing history is not zero growth. A channel risk signal is not proof of a Telegram shadowban.