# Twitter Ads

## Destination Info

* Supports [Track](https://documentation.freshpaint.io/developer/freshpaint-sdk-reference#track) calls
* Supports [HIPAA mode](https://documentation.freshpaint.io/hipaa-mode)
* Supports forwarding from the [Google Tag Manager Integration](https://documentation.freshpaint.io/integrations/google-tag-manager-integration)
* Refer to this destination as **Twitter Ads** in the [Integrations object](https://documentation.freshpaint.io/reference/developer/freshpaint-sdk-reference#using-the-integrations-object)
* Connection Modes:

<table><thead><tr><th align="right"> </th><th data-type="checkbox">Client-side</th><th data-type="checkbox">Server-side (Proxy)</th></tr></thead><tbody><tr><td align="right">Web</td><td>true</td><td>true</td></tr><tr><td align="right">Mobile</td><td>false</td><td>true</td></tr><tr><td align="right">Server</td><td>false</td><td>true</td></tr></tbody></table>

{% hint style="info" %}
When using Server-Side connection mode you are using a Proxy Integration for Twitter Ads. This destination runs on Freshpaint's servers, but emulates a native installation of the Twitter Ads Tag. That means the integration behaves the same as if you did a native installation of Twitter Ads, but the data first flows through Freshpaint before it's sent to Twitter. [See our docs on proxy integrations for more information](https://documentation.freshpaint.io/reference/faqs/what-is-a-proxy-integration).
{% endhint %}

## Getting Started

### Pixel ID

To configure your Twitter Ads destination, you'll first need to locate or generate a Pixel ID.

In your Twitter Ads account, select **Tools > Events Manager**. If you don't already have a Pixel ID, the page will guide you through adding a new Event Source.

Once you have a Pixel ID, you can use the copy button to **copy the Pixel ID** to your clipboard.

<figure><img src="https://1666823438-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MA7aDqsXMFbUsWVqonF%2Fuploads%2FsXRYZn0xCNWV3qntH2l2%2FScreen%20Shot%202023-03-07%20at%2015.18.06.png?alt=media&#x26;token=4a47ac2e-1521-4551-b20b-55901f9fe709" alt=""><figcaption></figcaption></figure>

### Configure Freshpaint destination

Once you have your Pixel ID, you can configure your [Twitter Ads destination](https://app.freshpaint.io/destinations/apps/twitter-ads) in Freshpaint.

<figure><img src="https://1666823438-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MA7aDqsXMFbUsWVqonF%2Fuploads%2Fr4mEh1DcwwxwPSfFSlO2%2FScreen%20Shot%202023-03-07%20at%2015.14.02.png?alt=media&#x26;token=6c836544-c1cf-4c1b-a1a8-b51d4ec936a1" alt=""><figcaption></figcaption></figure>

Once you've saved the Pixel ID, you're ready to start setting up conversion events in Twitter Ads!

### Configure Conversion Events

To send a conversion event to Twitter Ads, you need to set up an event in Twitter Ads and map your Freshpaint event to that event ID.

From the Twitter Ads Events Manager, click **Add Events**.

<figure><img src="https://1666823438-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MA7aDqsXMFbUsWVqonF%2Fuploads%2FpJTgljKyud2682K2Bkb3%2FScreen%20Shot%202023-03-06%20at%2016.34.40.png?alt=media&#x26;token=d1d84ad0-77ce-471b-9b09-88443ed7c1ac" alt=""><figcaption></figcaption></figure>

Give your event a name and click "Next".

<figure><img src="https://1666823438-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MA7aDqsXMFbUsWVqonF%2Fuploads%2Fp34YpnE8DdoX4bUUSs2A%2FScreen%20Shot%202023-03-06%20at%2016.35.20.png?alt=media&#x26;token=27d7c319-db21-4e22-ab93-8695ea6eb991" alt=""><figcaption></figcaption></figure>

Choose "**Define event with code**" and click "Next".

<figure><img src="https://1666823438-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MA7aDqsXMFbUsWVqonF%2Fuploads%2FzUizzw7iX38my9vLsQZ7%2FScreen%20Shot%202023-03-06%20at%2016.35.30.png?alt=media&#x26;token=3c5ffd6c-cbd2-4c79-9efa-9db27742a575" alt=""><figcaption></figcaption></figure>

Save your event and return to the Events Manager. Copy the **Event ID** (it looks like tw-xxxxx-xxxxx).

<figure><img src="https://1666823438-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MA7aDqsXMFbUsWVqonF%2Fuploads%2F9iO9bT4Y7B7LTVHGOKbY%2FScreen%20Shot%202023-03-06%20at%2016.36.55.png?alt=media&#x26;token=7a3b32fe-ceb2-4500-9840-6df389bc352d" alt=""><figcaption></figcaption></figure>

Return to the Freshpaint Twitter Destination and configure a transformation to map one of your Freshpaint events to the Twitter Event ID. Click "Configure" next to "Event Transformations".

<figure><img src="https://1666823438-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MA7aDqsXMFbUsWVqonF%2Fuploads%2FPIY9lGO0ssycS7NsFvWk%2FScreen%20Shot%202023-03-07%20at%2015.14.30.png?alt=media&#x26;token=b2785496-1e56-4f4a-8ae3-7993d3df7e61" alt=""><figcaption></figcaption></figure>

Click "**+ New Transformation**".

<figure><img src="https://1666823438-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MA7aDqsXMFbUsWVqonF%2Fuploads%2FWqdk6gBuylCaaBXDEJuo%2FScreen%20Shot%202023-03-07%20at%2015.14.39.png?alt=media&#x26;token=544c01c5-ad7e-4de7-ad64-b9b7f01684cc" alt=""><figcaption></figcaption></figure>

Select "**Standard Event**". Choose the event you'd like to send to Twitter Ads. Click "**Enable it**". Paste the Twitter **Event ID** in the final text box of this form and click "Save".

<figure><img src="https://1666823438-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MA7aDqsXMFbUsWVqonF%2Fuploads%2FGpaYeeTVZAAKTT5kJnhj%2FScreen%20Shot%202023-03-07%20at%2015.15.51.png?alt=media&#x26;token=28df1149-2817-4fc2-a1a7-fd7079ac23d5" alt=""><figcaption></figcaption></figure>

Once you've set up a transformation with the Twitter Event ID, you're ready to start sending events to Twitter Ads via Freshpaint!

### Using the GTM Integration

If using the [Google Tag Manager (GTM) Integration](https://documentation.freshpaint.io/integrations/google-tag-manager-integration), you should enter the Event ID (tw\* value) in the Event Name field and  define any other properties on the tag, for example:

<figure><img src="https://1666823438-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MA7aDqsXMFbUsWVqonF%2Fuploads%2FPZRfGKgsWXxwJCZahRGc%2FScreenshot%202025-09-09%20at%208.51.49%E2%80%AFPM.png?alt=media&#x26;token=b0b754aa-4c47-45e0-8e9d-989769312487" alt=""><figcaption></figcaption></figure>

### Check whether it's working

To check whether Twitter Ads is receiving events, you can go to **Tools > Events Manager** within your Twitter Ads account, which will show you when the last time twitter received an event for each destination.

<figure><img src="https://1666823438-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MA7aDqsXMFbUsWVqonF%2Fuploads%2Fgit-blob-00749700f7e3d33615b4a61e34fea637b1604320%2Ftwitter-ads-working.png?alt=media" alt="Twitter Ads working screenshot"><figcaption><p>Twitter Ads Working Screenshot</p></figcaption></figure>

## Track Events

Freshpaint can send **Events** to your Twitter Ads account, which enables you to perform conversion tracking within your Twitter Ads campaigns.

More information about Twitter Conversion Tracking is available in the [twitter docs](https://business.twitter.com/en/help/campaign-measurement-and-analytics/conversion-tracking-for-websites.html).

### Client-side

You may provide the following additional event properties when sending events to Twitter from the web:

| **Event property** | **Type** | **Required?** | **Description**                |
| ------------------ | -------- | ------------- | ------------------------------ |
| `quantity`         | number   | Optional      | Number of items purchased      |
| `revenue`          | number   | Optional      | Value of the conversion in USD |

### Server-side

{% hint style="info" %}
When using Server-Side connection mode you are using a Proxy Integration for Twitter Ads. This destination runs on Freshpaint's servers, but emulates a native installation of the Twitter Ads Tag. That means the integration behaves the same as if you did a native installation of Twitter Ads, but the data first flows through Freshpaint before it's sent to Twitter. [See our docs on proxy integrations for more information](https://documentation.freshpaint.io/reference/faqs/what-is-a-proxy-integration).
{% endhint %}

You may provide the following additional event properties when sending events to Twitter via Freshpaint's servers:

| **Event property**              | **Type** | **Required?** | **Description**                                                                                                                                                                                                              |
| ------------------------------- | -------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `$twclid`                       | string   | Required      | twclid is generated at ad click time and appended to the landing page URL. **Freshpaint will automatically capture twclid for events from your website**. For events from other sources you would need to provide `$twclid`. |
| `value` or `total` or `revenue` | number   | Optional      | Value of the conversion event                                                                                                                                                                                                |
| `currency`                      | string   | Optional      | Currency of the conversion value, "USD" by default. Can be any ISO 4217 code (e.g. USD, JPY, EUR).                                                                                                                           |

## Considerations

* Conversions may take up to 2 hours to appear in your Twitter Ads portal.