Twitter Conversions Connector Setup Guide
This article describes how to set up the Twitter Conversions connector.
This connector uses the following vendor API:
- API Name: Twitter Ads API
- API Version: v11
- API Endpoint:
- Rate limit: 60,000 events per account, per 15 minute interval
- Twitter Ads API access
- Twitter Developer account
- Twitter user account with permissions to send events to desired ad accounts
If you already have an actively used Twitter Ads API application, both the application and existing access tokens may be used for the Conversion API. For more information, see Conversion API Set Up in the Twitter documentation.
How it works
Use the Twitter Conversion API to create a separate server-side application that passes conversion events to Twitter for use in optimization, measurement, and attribution across your campaigns. With this API, you can measure the impact of running ads on Twitter by sending conversion events without the need for a Twitter website pixel.
Currently, there are two primary use cases for measuring ad impact using matching identifiers:
- Click-through conversions for website traffic campaigns using the Twitter Click ID
- View-through and click-through conversions for all Twitter campaigns using email
You can measure one or more of the following website actions with conversion tracking depending on your ad campaign:
- Site visit: User visits a landing page on an advertiser’s site
- Purchase: User completes a purchase of a product or service on the advertiser’s site
- Download: User downloads a file, such as a white paper or software package, from the advertiser’s site
- Sign up: User signs up for the advertiser’s service, newsletter, or email communication
- Custom: This is a catch-all category for a custom action that does not fall into one of the categories above
Using the Twitter Conversion API
To use the Twitter Conversion API, you need to create a new conversion event in the Twitter Ads Manager or use an existing event already created and used with the Twitter Pixel. To deduplicate conversions between Twitter Pixel and Twitter Conversion API requests, use the existing event you created for the Pixel.
Using an Existing Conversion Event in Ads Manager
To use an existing event used with the Twitter Pixel, use the Event ID from that event. If you use both Twitter Pixel and the Twitter Conversion API for the same event, ensure to use the deduplication key in both the Twitter Pixel code snippet and the Twitter Conversion API request (as
conversion_id). For more information about deduplication, see the Testing Events and Deduplication section in Conversion API Set Up in the Twitter documentation.
Identifiers for Conversion Events
For a conversion event to be passed in the Twitter Conversion API, there needs to be at least one Twitter Click ID (
twclid) or email address set as the as the event identifier.
To successfully setup conversion events to be passed to the Twitter Conversion API, we recommend the following configurations:
- Always parse the
twclidvalue when it is present in the URL query parameters to be passed to Tealium EventStream API Hub.
- Store the data alongside relevant form fields or conversion event information.
For Page View events, including Twitter-defined Site Visit and Landing Page View events, Twitter provides a 30 minute window for deduplication. Other event types, such as Purchase and Lead, are not deduplicated.
Manage event duplication using the
conversion_id event parameter, which can be included in Pixel or Twitter Conversion API requests.
|Send Conversion Event||✓||✓|
Twitter Conversions requires allowlisting on your Twitter account. For assistance with allowlisting, contact your Twitter representative..
Navigate to the Connector Marketplace and add a new connector. For general instructions on how to add a connector, see the About Connectors article.
After adding the connector, configure the following settings:
Event Source ID
The base-36 ID of a specific event, matching that of a pre-configured event contained within this ad account. This is called Website Tag ID in the Ads Manager, and Ads API and must be a Single Event Tag.
This value can be created in the following ways:
- Within the Single-Event Website tag configuration. Log in to your ads account at ads.twitter.com and select Events Manager under Tools.
- Use the API. See Web Event Tags for more details.
- Contact your Twitter account manager.
The Universal Website Tag (UWT) ID for an ad account. This represents the base36-encoded value for an ad account’s UWT ID.
To obtain your Pixel ID:
- Navigate to ads.twitter.com.
- In the top left corner of the interface, under Tools, click Events Manager.
- If you do not have a Twitter Pixel event source on your left sidebar yet, in the top right corner of the page, select Add event source.
- The interface displays the Pixel ID and Event ID of this event that is used in the API.
Action Settings — Parameters and Options
Click Continue to configure the connector actions. Enter in a name for the action and then select the action type from the drop-down menu.
The following section describes how to set up parameters and options for each action.
Action — Send Conversion Event
|Event Source ID Override||This is called Website Tag ID in the Ads Manager and Ads API and can be found in the Events Manager of the Twitter Ads platform. This is a required field, and this setting overrides Event Source ID used in the configuration section.|
|Conversion Time||The time of a conversion event. Specify date-time of event expressed in ISO 8601. If not provided, the time of the event is be used. Example:
|Twitter Click ID||Twitter Click ID as parsed from the click-through URL. Either Twitter Click ID or Email must be specified. Both are preferred in order to increase match rate.|
|Email Address (already SHA256 hashed)||Provide an email address which has been already whitespace trimmed, lowercased and SHA256 hashed.|
|Email Address (apply SHA256 hash)||Provide a plain text email address and the connector whitespaces trim, lowercase, and hash this value using SHA256 hash.|
|Conversion Value||The price value of items being purchased, represented in ‘price_currency’ currency.|
|Number of Items||The number of items being purchased. Must be a positive number greater than zero. If Number of Items is not provided, the total number of elements in the Contents array is used.|
|Currency||The type of a currency to filter results by, identified using ISO 4217. This is a three-letter string such as ‘USD’.|
|Conversion ID||For deduplication between pixel and conversion API conversions. An identifier for a conversion event that can be used for de-duplication between Web Pixel and Conversion API conversions in the same event tag. See the Conversions Guide for more information.|
|Description||Description with any additional information on the conversions.|
|Search String||Text that was searched for on the advertiser’s website.|
|Content ID||A SKU or GTIN identifier that represents the content.|
|Content Group ID||The ID associated with a group of product variants.|
|Content Name||The name of the product or service.|
|Content Price||The price of the product or service.|
|Content Type||The category for the product that was purchased.|
|Number of Items||The number of products purchased.|
Send Mobile Measurement Conversion Event
|Conversion Type||The type of conversion event. Possible values:
|Hashed Device ID||(Required)|
|Operating System Type||(Required)|
|Device IP Address||IPv4 or IPv6 address of the device when the conversion event happened.|
|Click Window||The click window for this event in days. Note: Click Window must be greater than or equal to View Through Window. Default:
|Level||A level associated with this event.|
|Non Twitter Engagement Time||The time of the last non-Twitter engagement prior to the conversion.|
|Non Twitter Engagement Type|
|Number Items||Number of items associated with this event.|
|Price Currency||The currency associated with this event in ISO 4217 format.|
|Price Micro||A price amount associated to this event in micro.|
|User Payment Info||A boolean value to indicate if the user’s payment information is stored in the app associated with this event.|
|View Through Window||The view through window for this event in days. Default:
Thank you for your feedback!
This page was last updated: September 27, 2022