> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hightouch.com/llms.txt
> Use this file to discover all available pages before exploring further.

# X Ads (formerly Twitter Ads)

> Send conversion web events to X and run campaigns with custom audiences, retargeting, and lookalikes directly from your warehouse

## Overview

Build more robust campaigns on X (formerly Twitter) with up-to-date customer data from your data warehouse.

## Supported syncing

| Sync type | Description | Supported sync modes |
| - | - | - |
| [**Custom audiences**](#syncing-custom-audiences) | Create audience lists and keep them up-to-date in X | Add |
| [**Conversion events**](#syncing-conversion-events) | Sync web conversion events to X | Insert |

For more information about sync modes, refer to the [sync modes](https://docs.hightouch.com/syncs/types-and-modes.md#sync-modes) docs.

## Connect to X

1. Go to the [**Destinations** overview page](https://app.hightouch.com/destinations?from=docs) and click the **Add destination** button.
2. Select **X** in the destination catalog and click **Continue**.
3. Proceed with the OAuth steps until you are redirected to the Hightouch website.
4. Give your destination a name and unique slug (for example, “X Production” and `x-production`).
5. Click **Finish** to create your X destination.

## Sync configuration

### Syncing custom audiences

This integration supports *Segment Mode*. New users in the model will be inserted into the X
Custom Audience. Users that are removed from the model will be removed from the
Custom Audience.

#### X account selection

In this section, select the X account you would like to sync your data to.

#### Audience selection

This integration supports syncing to an **existing audience** or **creating a new audience**.

To use an **existing segment**:

* Select `Use existing audience` from the radio buttons.
* Select the name of the audience from the dropdown menu.

To **create a new audience**:

* Select `Create a new audience` from the radio buttons.
* Specify a custom name for this audience in the input field. Otherwise Hightouch will use the name of the model as the audience's name.

#### User identifers

Hightouch allows you to sync columns from your source to the supported X fields.

X allows mapping to various user identifiers, such as Email, Device ID, X Handle, etc. X requires *all fields* for users
to be both **normalized** and **hashed** using SHA256 (with the exception of Partner User ID).

You can achieve this in your model with a function
by using the `encode(digest(value, 'sha256'),'hex')` function in Postgres, or refer to the [Template Mappings](https://docs.hightouch.com/destinations/x.md#template-mappings) Section in this documentation to learn about how Hightouch can handle hashing these records for you.

> [!NOTE]
>
> If you map an identifier field that contains an array of values, Hightouch automatically fans out each element into a separate record when syncing to X. Learn more about [array identifier fan-out](https://docs.hightouch.com/syncs/array-identifier-fan-out.md).

### Syncing conversion events

This integration supports syncing *Web Conversion Events*.

> [!WARNING]
>
> To ensure syncs send each event, your event model must use a truly unique [primary key](https://docs.hightouch.com/getting-started/concepts.md#unique-primary-key-requirement). See the [events syncs](https://docs.hightouch.com/syncs/types-and-modes.md#event-syncs) documentation for more information.

#### X account selection

In this section, select the X account you would like to sync your data to.

#### Pixel ID (Universal Website Tag) account section

If the **Pixel ID** exist in your model, toggle **Use Column**, and select the appropriate column from the dropdown menu.

To retrieve your Pixel ID:

* Navigate to your [Events Manager](https://business.x.com/en/help/campaign-measurement-and-analytics/conversion-tracking-for-websites) page.

![Where to find Pixel ID](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-x-pixel-id.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=064cec4d2bf80f4d7b59e6fad2b986b1)

* Copy the ID and paste it in the Hightouch sync form.

#### Event selection

Given the correct **Pixel ID**, Hightouch will filter for the eligible events that allow conversion events to be synced to.

Select the event you'd like to sync to from the dropdown menu. If the **ID** for these events exist in your model, toggle **Use Column**, and select the appropriate column from the dropdown menu.

#### Identifier section

When syncing conversion events, X expects one identifier at minimum, or you can provide both.

Select your choice for the sync from the radio buttons. This will render the fields in the mappings section, which you can map to from your model.

#### Field mapping

Hightouch allows you to sync columns from your source to the supported X fields.

If you wish to use the **Email Address** as an identifier, X expects it to be hashed using SHA256.
You can achieve this in your model with a function by using the encode(digest(value, 'sha256'),'hex') function in Postgres, or refer to the [Template Mappings](https://docs.hightouch.com/destinations/x.md#template-mappings) section in this documentation to learn about how Hightouch can handle hashing these records for you.

### Template mappings

You can leverage Hightouch's Template Mappings feature to allow Hightouch to handle hashing certain fields for you automatically.

To use this feature:

* Select **Template** in the mappings window.
* Select the column you would like to hash from the **Variables** section.
* Select **sha256** from the **Functions** section.
* Click **Apply** to save.

![Template Mappings Instruction](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-x-template-mappings.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=aeb860ba977ae5f2a5e2ed116ec43cfc)

To find out more about Template Mapping and other Mapping features, visit our [Mapping Data](https://docs.hightouch.com/syncs/mapping-data.md) section.

## Tips and troubleshooting

To see the exact API requests and responses from each sync run, use the [live debugger](https://docs.hightouch.com/syncs/debugger.md). To get notified by Slack, PagerDuty, SMS, or email when a sync fails, set up [sync alerts](https://docs.hightouch.com/syncs/alerting.md). If you run into an issue this page doesn't cover, [contact support](#pylon-chat).

Below only applies to the audiences sync type.

Hightouch retrieves the audience metadata from X in real-time. The matched number displayed in Hightouch should reflect what you see in X. Note that the matched numbers are approximated to maintain privacy thresholds. Hightouch takes the matched count to calculate a match rate for your sync, where applicable. The calculation breakdown:

`matched_user_count / # of rows queried in the latest sync run`

The match rate is **not** calculated when:

* syncing to an existing segment because the total number of records to ever be uploaded to the segment is unknown
* removed users from your model is not removed in X because the matched user count would be inflated in the calculation

Common causes for low match rates:

* Your audience model is too small. Most ad platforms do not display the matched number unless there's at least one thousand matched users to maintain privacy thresholds.
* The upload is still processing. We recommend waiting at least **72 hours** from the first sync run for numbers to settle.
* Your data isn’t cleaned or hashed properly. Hightouch normalizes and hashes your data according to destination requirements, but it’s still good to make sure that the data is as clean as possible. Note that Hightouch cannot clean your data if you opt to hash it yourself. In that case, ensure you follow the data cleaning requirements for X.

## Common errors

### 400: INVALID\_PARAMETER

The full error message looks something like this:

```json theme={null}
{
  "request": [
    {
      "params": {
        "account_id": "01ab234cdef",
        "custom_audience_id": "0a1b2"
      },
      "operation_type": "Update"
    }
  ],
  "operation_errors": [
    [
      {
        "code": "INVALID_PARAMETER",
        "message": "Tailored audience attribute value can not be empty.",
        "parameter": ""
      }
    ]
  ]
}
```

This error occurs if any of your [field mappings](#field-mapping) include `null` values.
X doesn't accepted hashed `null` values.
To resolve this, [remove rows containing `null` values](https://docs.hightouch.com/models/sql-editor#exclude-rows-with-null-values) from your model's query results or enable the [**Don't sync null values** option](https://docs.hightouch.com/syncs/mapping-data.md#dont-sync-null-values) in the [advanced mapper](https://docs.hightouch.com/syncs/mapping-data.md#advanced-mapper).