Conversions (postbacks in)

Telegram counts views, clicks and joins. Your backend or tracker knows what happened next — a lead, a deposit, a sale. Send those events to Adsly and each campaign shows its conversions and revenue in the panel, in reports and in automation rules.

Turn it on

On the key’s card in the panel, switch on Receive postbacks. Without it, sending returns 403 INGEST_DISABLED. For a tracker, also press Generate tracker URL — you get a write-only URL (shown once) that can post conversions but can’t read anything.

How a conversion finds its campaign

Each ad links somewhere with an identifier you control:

• a bot or mini-app: t.me/yourbot?start=REF or ?startapp=REF
• a website: your tracker’s click id or sub id in the link, e.g. https://site.com/?subid=REF

When you send a conversion, include that REF as ref. Adsly finds the campaign whose link carries it, in the cabinets the key reaches. If several campaigns of one cabinet share the same ref, the conversion counts for each of them.

From your backend: POST /v1/postback

curl -s -X POST https://app.adsly.pro/api/v1/postback \
  -H "X-API-Key: $ADSLY_API_KEY" -H "Content-Type: application/json" \
  -d '{ "ref": "promo_oct", "event": "purchase", "amount": 49.90, "currency": "USD", "txid": "order-10087" }'

{ "success": true, "data": { "id": 551203, "ad_id": 90412, "account_id": 53, "event_type": "purchase", "deduped": false } }

Up to 1,000 events at once: { "events": [ {…}, {…} ] } (or a bare array). The response reports each one — { "accepted": 998, "failed": 2, "results": [ … ] } — so one bad event never sinks the batch.

From a tracker: GET /v1/ingest/{token}

Paste the tracker URL into your tracker’s postback settings, with its macros:

# Keitaro
https://app.adsly.pro/api/v1/ingest/<token>?ref={subid}&event={status}&amount={payout}&currency={currency}&txid={subid}_{status}
# RedTrack
https://app.adsly.pro/api/v1/ingest/<token>?ref={clickid}&event={type}&status={status}&amount={sum}&txid={rdtk_event_id}
# Binom
https://app.adsly.pro/api/v1/ingest/<token>?ref={clickid}&event={status}&amount={payout}&txid={clickid}
# Voluum
https://app.adsly.pro/api/v1/ingest/<token>?ref={clickid}&event={et}&amount={payout}&currency={currency}&txid={txid}

Check the macro names against your tracker’s own documentation. The answer is plain text: OK, OK (deduped), or an error message with its HTTP status (4xx — don’t retry, 5xx — retry).

Fields

Field	Also accepted as	Required	Meaning
ref	subid, sub_id, clickid, click_id, cnv_id, cid	yes¹	The identifier from the ad’s link. Up to 512 characters.
invite_link	invitelink, link	yes¹	For channel ads: the unique invite link Adsly created.
event	event_type, type, goal, cnv_status	yes	Becomes lead, conversion or purchase (words like signup, ftd, deposit, sale are understood). Unknown words are refused.
txid	tid, transaction_id, order_id, rdtk_event_id, header X-Idempotency-Key	yes	Your id for this event. Sending the same txid again updates the event instead of counting it twice. Up to 128 characters.
amount	payout, sum, revenue, value	no	Number; negative for chargebacks.
currency	cur, cnv_currency	no	ISO 4217 code. Without one, an amount is recorded as USD.
status	—	no	Your network’s own status word (approved, pending…), stored as is.
event_time	timestamp, date	no	ISO or unix time; kept within the last 90 days.
account_id	accountId	sometimes	Needed when the same ref exists in several of your cabinets (409 otherwise).
meta	—	no	Your own JSON object, up to 4 KB.

¹ ref or invite_link.

Limits and retries

20 events per second per key, with bursts up to 1,000 — separate from the read and write budgets. On 429 wait Retry-After; retrying is always safe because txid deduplicates.

GET /v1/conversions

Totals per campaign, counted once per event:

curl -s "https://app.adsly.pro/api/v1/conversions?days=30" -H "X-API-Key: $ADSLY_API_KEY"

{
  "success": true,
  "data": [
    { "account_id": 53, "ad_id": 90412, "leads": 12, "conversions": 3, "purchases": 1, "revenue": { "USD": 49.9 } }
  ]
}

Parameter	Meaning
adId	One campaign.
days	Only events received in the last 1–365 days.

• revenue is per currency — amounts are never converted.
• ad_id is null for events matched by a ref that several campaigns share.
• Amounts you send are your own reporting. They are not billed and don’t change anything you pay Adsly.