TikTok Events API

This guide explains how to configure the Events API events AdTarget sends to TikTok when users join your Telegram channel.

When Are Events Sent?

AdTarget sends an event to TikTok only for attributed joins — meaning joins where AdTarget can match the Telegram join back to a specific ad click on your landing page. This requires the invite_link to be present in Telegram’s webhook.

Events are sent when a user clicks your tracked invite link and Telegram reports it in the webhook (reliable for private channels).

Events are NOT sent for organic joins — users who find your channel via search, direct links, or forwarded messages. These joins still appear in your AdTarget dashboard but are marked as “organic.”

Public channel limitation: Due to a Telegram API limitation, even users who click your tracked link may be treated as organic joins on public channels. Telegram’s app (especially Android) often converts invite-link joins into “direct joins” for public channels, stripping the attribution data. Learn more →

Available Event Types

AdTarget maps its event types to TikTok’s standard events:

AdTarget Event	TikTok Event	Best For	TikTok Optimization
Lead	SubmitForm	Lead generation campaigns	Optimizes for form submissions
Purchase	Purchase	Purchase-focused campaigns	Optimizes for purchase actions
CompleteRegistration	CompleteRegistration	Signup-focused campaigns	Optimizes for registration actions
Subscribe	Subscribe	Subscription campaigns	Optimizes for subscription intent
Custom	Your custom name	Specialized tracking	Custom optimization

Choosing the Right Event

Running lead gen ads? Use Lead (maps to TikTok’s SubmitForm) — This tells TikTok “this person submitted a form / became a lead.”

Selling a product or service? Use Purchase — Best when you want TikTok to optimize for buyers. Pair it with a value and currency in your channel’s conversion config for value-based optimization.

Running signup campaigns? Use CompleteRegistration — Signals a completed registration action.

Promoting a channel subscription? Use Subscribe — Matches the user action (joining = subscribing).

Need a non-standard event? Use Custom — Lets you define your own event name for specialized tracking scenarios.

Tip: Match your event type to your campaign objective in TikTok Ads Manager for best results.

Configuring Events

Event types are configured per channel. Each channel defaults to CompleteRegistration when first detected.

To change a channel’s event type:

Go to your site’s Settings → Channels tab
Click Setup (or Edit) on the channel row
Select your event type in the dialog
Click Save

Event Parameters

Each event AdTarget sends to TikTok includes these parameters:

Required Parameters

Parameter	Description
`event`	The TikTok event name (SubmitForm, Purchase, etc.)
`timestamp`	ISO 8601 timestamp of the join
`event_id`	Unique deduplication ID

Attribution Parameters

Parameter	Description
`context.ad.callback`	The `ttclid` from the ad click (TikTok Click ID)

User Data

Parameter	Source	Hashed?
`context.user.external_id`	Telegram user ID	Yes (SHA-256)
`context.ip`	IP from landing page visit	No (sent as-is)
`context.user_agent`	Browser from landing page visit	No (sent as-is)

The external_id (Telegram user ID) is SHA-256 hashed before sending, as required by TikTok. IP address and user agent are sent as-is per TikTok’s Events API specifications.

Event Properties

Parameter	Description
`properties.value`	Event value (if configured per channel)
`properties.currency`	Currency code (defaults to `"USD"`)
`properties.content_name`	Channel title or custom name from channel config

Event Deduplication

AdTarget includes a unique event_id with each event to prevent duplicates:


event_id: "adtarget_{conversion_id}"

This ensures the same conversion isn’t counted twice, even if retried.

Testing Events

Test in Production

The most reliable way to test end-to-end:

Click your own TikTok ad (or use a test ad)
Visit your landing page
Join your Telegram channel via the tracked invite link
Check TikTok Events Manager within 5-10 minutes

Verify in TikTok Ads Manager

Go to Assets → Events → Web Events → Manage
Check the Events tab
Look for your event type with recent timestamps
Verify the event shows as “Received”

Event Matching

TikTok matches your events to users for attribution. Higher match quality means better optimization.

Match Quality Factors

Factor	Impact
ttclid present	High - Direct click attribution
User agent + IP	Medium - Probabilistic matching
External ID	Medium - Cross-device matching

Improving Match Quality

Capture ttclid: Ensure your landing page URL preserves the ttclid parameter
Send events promptly: Shorter time between click and conversion improves matching
Consistent user journey: Keep users on your domain before redirecting to Telegram

Common Event Configurations

Lead Generation


AdTarget Event: Lead → TikTok Event: SubmitForm
When: User joins channel
Use Case: "Get subscribers" campaigns

Purchase Tracking


AdTarget Event: Purchase → TikTok Event: Purchase
When: User joins channel
Use Case: "Buy now" campaigns with value-based optimization

Content Subscription


AdTarget Event: Subscribe → TikTok Event: Subscribe
When: User joins channel
Use Case: "Subscribe to channel" campaigns

Troubleshooting

Events not matching?

Check ttclid is in the landing page URL
Verify TikTok Pixel is also on the landing page
Ensure cookies aren’t blocked

Low event match rate?

Reduce time between click and conversion
Verify ttclid is being captured from the URL
Ensure IP and user agent are available

Duplicate events?

AdTarget handles deduplication automatically via event_id
If seeing duplicates, contact support

Best Practices

Match event type to campaign objective for better optimization
Use the same event type consistently within a campaign
Monitor event delivery in TikTok Events Manager regularly
Test before scaling ad spend

Next Steps

Your TikTok integration is complete! Start running ads and watch your conversions flow into TikTok.

Need help optimizing? Contact our support team.