The X (Twitter) Conversion API Tag for Google Tag Manager Server-Side allows you to send conversion events from your server container directly to X (Twitter) servers. This server-to-server integration offers a more robust and secure way to track conversions and user data.
Features
- Server-to-Server Events: Sends conversion data directly from the GTM Server Container to X (Twitter)'s Conversion API.
- Access Token Authentication: Simple, recommended authentication using a single Access Token generated from your X Ads Manager.
- OAuth Authentication: Legacy OAuth 1.0a authentication is still supported but will be removed in December 2026. Migrate to Access Token.
- Flexible Data Mapping: Allows overriding server event data and adding specific user data.
- Automatic Data Hashing: Automatically hashes user data like email and phone numbers using SHA-256 if they are not already hashed.
- Cookie Management: Optionally persists the Click ID (
twclid) as a first-party cookie, with configurable expiration, SameSite and HttpOnly settings. - Click ID and Browser ID Recovery: Reads the
twclidClick ID from the URL, first-party cookie, the X pixel’s own_twclidcookie, or the event data, and reads thetwpidBrowser ID from the_twpidcookie set by the X pixel.
Installation
- Import to GTM Server Container:
- In your GTM Server Container, navigate to the Templates section.
- Click Search Gallery under the Tag Templates section.
- Search for the Twitter Conversion API tag and click Import.
- Create a New Tag:
- Go to Tags and click New.
- Select the newly imported “Twitter Conversion API” tag.
Tag Configuration
Base Configuration
| Parameter | Description |
|---|---|
| Authentication Method | Choose between Access Token (recommended) or OAuth (legacy, removed December 2026). |
| Access Token | (Access Token method) The token generated from your X Ads Manager. Go to Events Manager → Install Pixel → Manual → Conversions API → Generate access token. |
| Pixel ID | The Pixel ID for your ad account. |
| Event ID | The ID of a specific event. It matches a pre-configured event contained within this ad account. |
| Consumer Key | (OAuth method) Your Twitter App Consumer API Key. |
| Consumer Secret | (OAuth method) Your Twitter App Consumer API Secret. |
| OAuth Token | (OAuth method) Your Twitter App Authentication Token. |
| OAuth Token Secret | (OAuth method) Your Twitter App Authentication Token Secret. |
| Use HttpOnly cookies | Forbids JavaScript from accessing the cookie if enabled. |
| Use Optimistic Scenario | The tag will call gtmOnSuccess() without waiting for a response from the API. This will speed up sGTM response time however your tag will always return the status fired successfully even in case it is not. |
OAuth authentication will be removed in December 2026. If you are currently using OAuth, migrate to the Access Token method.
Click ID Cookie Settings
| Parameter | Description |
|---|---|
| Set Click ID cookie | Enabled by default. When enabled, a twclid found on the URL is persisted as a first-party cookie so it can be reused on subsequent hits. When disabled, an existing Click ID is still sent with the event, just not stored. |
| Cookie SameSite | None, Lax (default), or Strict. |
| Cookie Expiration | Cookie lifetime in days. Defaults to 390. |
Server Event Data Parameters
| Parameter | Description |
|---|---|
| Server Event Data Override | Manually override or add server event data parameters. Available properties: Conversion Time, Conversion Timestamp, Number Items, Currency, Value, Conversion ID, Description, Contents, Search String, Event Source URL. |
See this documentation for more details on what data parameters you can override.
User Identifiers Parameters
| Parameter | Description |
|---|---|
| User Data | Manually add user identifiers. Supported types: Email, Phone, Click ID (twclid), Browser ID (twpid), IP Address, and User Agent. All identifiers are sent to X as a single object. |
At least one identifier must always be sent. Browser ID (twpid), IP Address, and User Agent each require a companion identifier (Click ID, Email, Phone, or one of the others in that group).
If the automapped email or phone number from your event data is an array (e.g. user_data.email_address: ["a@test.com", "b@test.com"]), the tag uses the first value in the array.
See this documentation for more details on what user data parameters you can add to the call. If the documentation requires the parameter to be hashed, you must hash it with SHA256, or the tag will do this automatically before sending the event to Twitter.
Useful Resources
Open Source
The X (Twitter) Conversion API Tag for GTM Server-Side is developed and maintained by the Stape Team under the Apache 2.0 license.
