Connect X Ads

TrueEngage sends mapped events to X as conversions, through the X Conversions API. You connect by pasting an app's API keys and an access token. There is no X sign-in screen, and X takes events only: audiences are not supported.

Before you start

• You need Create and manage on Ad platforms.
• You need an X ads account, and a website tag (pixel) in it to send conversions.
• You need an app in the X developer portal that has been approved for Ads API access. X refuses signed requests from an app without it.
• The user the access token belongs to must have access to the ads account.

Find the values

Value	Where to find it
Ads account ID	Open your ads account in X Ads. The ID is the short run of letters and numbers in the page address after the account section. It is also listed in the account switcher
Pixel ID (optional)	In X Ads, open Events Manager (under Tools) and copy the ID of the website tag you use for conversion tracking. Without it the connection saves, but no events are sent
API key and API key secret	In the X developer portal, open your project's app and go to Keys and tokens. These are the consumer keys. Regenerate them if the secret was not saved
Access token and Access token secret	On the same Keys and tokens page, under Authentication Tokens, select Generate. Set the app's permissions first, so the token is made with them

All four keys and tokens must come from the same app. A token generated in the portal belongs to the app's owner, so that user needs access to the ads account.

Connect

1. Open Data, then Ad platforms.
2. On the X Ads card, select Connect with credentials.
3. Enter a Name, the Ads account ID and, if you have it, the Pixel ID. Select Continue.
4. Enter the API key, API key secret, Access token and Access token secret. All but the API key hide what you paste.
5. Select Connect and check.
6. Read the check, then select Open connection.

TrueEngage verifies the keys while it saves them. If X refuses them, the dialog stays on the keys step and says why, and nothing is saved. Fix the value and select Connect and check again.

TrueEngage stores the secrets and tokens encrypted and never shows them again.

Read the check

TrueEngage runs one check: Access to the ad account. It passes when X accepts the signed request and the ads account can be read.

X has no endpoint for validating a test event, so there is no test event check. A passing check means the keys work, not that a conversion has arrived. After your first send, open the connection's activity and confirm the event was accepted.

What is sent

• Events go to your website tag through the Conversions API, in batches.
• People are matched on a hashed email and a hashed phone number. TrueEngage hashes them with SHA-256 before they leave. Users with neither are skipped.
• Each event carries an ID that X uses to drop duplicates.
• X accepts events up to 90 days old. TrueEngage queues only events inside that age.
• X Ads has no audiences. The connection has no Audiences tab.

Choose which events to send in Send events as conversions. X's standard event names, such as Purchase and Lead, are offered as destinations. A Purchase needs a value.

Replace credentials

When X stops accepting the keys, the connection shows Reconnect needed. Open it, select Enter new credentials, and paste only the values that changed. Leave a field empty to keep what is stored. If you regenerate the API keys, the access token usually has to be generated again too, so paste all four. TrueEngage checks the new values before it resumes sending. See Fix connection errors and reconnect.

Common problems

• X does not accept these keys and tokens. Check that all four were copied in full from the same app, and that the access token was generated after the app's permissions were set.
• The ads account cannot be reached. Check the ads account ID, and that the user who owns the access token has access to that ads account.
• The app is not approved for Ads API access. X refuses every signed request. Apply for Ads API access in the developer portal.
• X is busy. Wait a few minutes and check again. X rate limits requests.

What happens next

• Send events as conversions
• Ad platform error codes