> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.funnelflux.pro/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# Direct integration setup with TikTok

This guide walks through our native TikTok integration from start to finish.

Once it's set up, we send your conversions and custom events straight to TikTok's Events API, pull campaign spend into your reports, and show your campaign, ad group and ad names instead of raw IDs.

If you're unsure about any of the settings below, use our **TikTok** traffic source template when you create the traffic source. Everything will be configured correctly.

If you haven't yet, read [Using traffic source integrations](https://help.funnelflux.pro/en/article/using-traffic-source-integrations-s4p02b/) first -- it explains the general flow (connections, traffic source link, event mapping) that applies to every platform. This article only adds the TikTok-specific parts.

Note that the older method, where you build a TikTok custom scenario with your own access token, still works and is described in [Using the TikTok API for tracking conversions](https://help.funnelflux.pro/en/article/using-the-tiktok-api-for-tracking-conversions-zg0o3o/). For new setups we recommend the native integration -- there is no token to copy around, and you get cost and name sync on top.

## Step 1: Connect your TikTok account

Go to Settings > Integrations > Traffic Sources and find the **TikTok** card.

Click **Connect** (or **Add account** if you already have a TikTok connection) and you'll be sent to TikTok for Business to log in and approve access.

Log in with the TikTok login that has access to the ad accounts you advertise from.

![Traffic Source Integrations settings with the TikTok card highlighted](https://storage.crisp.chat/users/helpdesk/website/-/b/7/4/9/b749232d828ce800/01-settings-tiktok-card_1m5qz4.png)

When you come back, the connection appears under **Connections** with an **Active** status.

If it ever shows Expired or Auth error, click **Reauth** to log in again.

## Step 2: Link the traffic source to your TikTok ad account

Open your TikTok traffic source (or create one from the TikTok template) and go to the **Integrations** tab.

In **Platform Integration**, fill in the fields from top to bottom -- each one appears once the previous one is set:

1. **Traffic Source Integration Type** -- TikTok. If the traffic source used our TikTok custom scenario before, or has "TikTok" in its name, we pre-select this for you.
2. **Connection** -- the TikTok login you connected in Settings.
3. **Ad Account** -- the TikTok ad account this traffic source spends from.
4. **Event Source / Pixel Code** -- the TikTok pixel that events should be sent to.
5. **TikTok Test Event Code** -- optional, see below.

![TikTok traffic source Integrations tab with connection, ad account and pixel selected](https://storage.crisp.chat/users/helpdesk/website/-/b/7/4/9/b749232d828ce800/02-platform-integration_zyos69.png)

The chips at the top right (**Platform** > **Connection** > **Ad account** > **Event Source / Pixel Code**) turn green as each step is done.

### Picking the pixel

Once the ad account is selected, we load the pixels from that account, so you can just pick one from the **Event Source / Pixel Code** dropdown.

If your pixel isn't listed, or the list fails to load, click **Enter ID manually** and paste it in. **Select from account pixels** switches back to the list.

When entering it manually, use the pixel code shown in TikTok Events Manager (the same code that's in your pixel's JS snippet). Do NOT use the numeric pixel ID from TikTok's Marketing API -- TikTok rejects events sent to that one with a permission error.

### Test event code

**TikTok Test Event Code** is optional.

If you copy a test code from the Test Events tab in TikTok Events Manager into this field, the events we send are routed to TikTok's Test Events view, so you can watch them arrive while checking your setup.

Clear it once you're done testing, so your events go to the pixel normally.

## Step 3: Check your tracking fields

TikTok matches conversions back to ad clicks mainly using the TikTok click ID, `ttclid`.

For us to send it, the click ID needs to be captured in the **External Click ID** tracking field. On the **Tracking Fields** tab, check that the External Click ID row has `ttclid` as the URL parameter and `__CLICKID__` as the source token.

![Tracking Fields tab with the External Click ID row carrying ttclid](https://storage.crisp.chat/users/helpdesk/website/-/b/7/4/9/b749232d828ce800/04-tracking-fields_1effxds.png)

If you created the traffic source from our TikTok template, this is already done for you.

A few other things also help TikTok match events, and we send them automatically where available:

- The `_ttp` browser cookie, picked up by our JS tag when it's present on your page.
- The URL of the lander or offer page the visitor was on, plus the referrer.
- Email, phone and external ID when we have them for that visitor, hashed before sending.

## Step 4: Map your events

Go to the **Conversion Tracking** tab and switch the toggle at the top from **Classic Options** to **Integrations**.

![Integration Event Mapping for TikTok with Conversions mapped to a TikTok event](https://storage.crisp.chat/users/helpdesk/website/-/b/7/4/9/b749232d828ce800/05-event-mapping_9oqen1.png)

For each event you want to send:

1. Pick a **Triggering Event** -- **Conversions** or one of your custom events.
2. Pick a **Destination Event** -- one of TikTok's standard events such as Complete Payment, Add to Cart or Submit Form, or type your own custom event name.
3. Optionally set a **Value Override**, **Currency Override** or webhooks.

Each TikTok event can only be used once per traffic source, so one conversion is never counted twice in TikTok.

Remember that saving in Integrations mode removes the traffic source's classic postback and custom scenario settings. That's on purpose -- otherwise TikTok would receive every conversion twice. If you're moving over from the old TikTok custom scenario, note down your settings first in case you want to go back.

Then click **Save**.

TikTok has no delay on conversions, so they are sent as soon as they happen.

## Step 5: Turn on cost sync and name sync

Back on the **Integrations** tab, below Platform Integration, you'll find **Cost Sync** and **Dictionary Sync**.

![Cost Sync and Dictionary Sync sections for a TikTok traffic source](https://storage.crisp.chat/users/helpdesk/website/-/b/7/4/9/b749232d828ce800/06-cost-and-dictionary-sync_73ogq9.png)

**Cost Sync**

- **Enable campaign-level cost sync** -- imports campaign spend from TikTok every hour.
- **Reconcile finalized daily costs** -- rechecks each finished day once TikTok has finalized its numbers, so your costs end up matching TikTok's own reporting.

After saving, the **Sync status** panel shows the last and next runs, and you can use **Sync hourly costs now** or **Reconcile daily costs now** if you don't want to wait.

Note that this is campaign-level ONLY. If you need spend per ad group or per ad, that's available through Argosync -- click **Learn more** in that section.

**Dictionary Sync**

Turn on **Enable ID to name sync** and we'll pull your campaign, ad group and ad names from TikTok, so reports show "US - Broad - Video 3" instead of a long number.

The table shows which tracking fields we need. For TikTok these are:

| Level | URL value |
|---|---|
| Campaign | `__CAMPAIGN_ID__` |
| Ad Group | `__AID__` |
| Ad | `__CID__` |

If a row says **Add field**, add a tracking field with that URL value. We match on the URL value, not the field name, so it doesn't matter what you call it. The TikTok template already includes all three.

**Show original IDs after synced names** keeps the raw ID next to the name, handy when you need to search for it in TikTok Ads Manager.

## Checking that events arrive

Go to Logs > Integration Logs.

The **Event Logs** view lists every event we sent to TikTok: when it was sent, which traffic source it came from, the event type, the destination event, the outcome (e.g. **Delivered**), and what data was included, such as URL and click ID.

Use the **Platforms** filter to show only TikTok, and widen the date range if you're looking for older events.

Switch to the **Queue** view with the toggle next to **Apply**. It lists events that haven't been sent yet -- **Pending**, **Processing** or **Held** -- with their status, hold reason, platform, integration, traffic source, hit ID and event type.

### Held conversions

If your TikTok connection expires, is disconnected, or the link is misconfigured, we don't throw conversions away. They are held in the queue and sent once you fix the problem.

In the Queue view, held rows show the **Hold Reason**: Credentials invalid, Integration inactive or Configuration error.

Turn on the **Resolution** and **Next Attempt** columns under **Columns** to see what to do about it -- e.g. "Reconnect TikTok integration", which links to the settings page -- and when we retry. For held rows, Next Attempt reads "After fix": nothing is retried until the problem is solved.

Other platforms limit how late a conversion can be uploaded, so their held conversions eventually expire. TikTok doesn't publish such a limit, so held TikTok conversions stay in the queue until you reconnect.

Note that completed items drop out of the Queue view by default. Completed only means the item left the queue -- Event Logs tells you whether TikTok actually accepted it.

## Troubleshooting

**The pixel list is empty or won't load**

Click **Enter ID manually** and paste the pixel code from TikTok Events Manager. Also check that the TikTok login you connected has access to that pixel.

**Events fail with a permission error**

Usually this means the pixel ID is the numeric Marketing API ID rather than the pixel code, or your login doesn't have access to that pixel. Re-select it from the list, or check the code in Events Manager.

**Events arrive in TikTok but don't attribute to ads**

Check the **External Click ID** tracking field carries `ttclid` with `__CLICKID__`, and that your TikTok ads use the tracking link from this traffic source.

**My events only show under Test Events**

Clear the **TikTok Test Event Code** field and save.

For anything else, see the troubleshooting section in [Using traffic source integrations](https://help.funnelflux.pro/en/article/using-traffic-source-integrations-s4p02b/).