Skip to main content
Ask your AI

X (Twitter) Conversions API

Server Source code Package Beta

Server-side event delivery to X's (Twitter's) Conversions API for ad attribution.

Where this fits

X Conversions API is a server destination in the walkerOS flow:

Sends conversion events server-side to X's Conversions API, bypassing browser limitations for improved data quality. Sends the event's `id` as `conversion_id`, so X can deduplicate it against the X Pixel.

Installation​

npm install @walkeros/collector @walkeros/server-destination-twitter
import { startFlow } from '@walkeros/collector';
import destinationTwitter from '@walkeros/server-destination-twitter';

await startFlow({
  destinations: {
    twitter: {
      code: destinationTwitter,
      config: {
        settings: {
          pixelId: 'o8z6j',
          eventId: 'tw-o8z6j-o8z21',
          consumerKey: process.env.TWITTER_CONSUMER_KEY,
          consumerSecret: process.env.TWITTER_CONSUMER_SECRET,
          accessToken: process.env.TWITTER_ACCESS_TOKEN,
          accessTokenSecret: process.env.TWITTER_ACCESS_TOKEN_SECRET,
        },
      },
    },
  },
});

Configuration​

This destination uses the standard destination config wrapper (consent, data, env, id, ...). For the shared fields see destination configuration. Package-specific fields live under config.settings and are listed below.

Settings​

PropertyTypeDescriptionMore
pixelId*stringX Pixel ID used in the Conversions API endpoint URL
eventId*stringDefault pre-registered conversion event ID
consumerKey*stringOAuth 1.0a API Key (Consumer Key) for X Ads API
consumerSecret*stringOAuth 1.0a API Key Secret (Consumer Secret)
accessToken*stringOAuth 1.0a User Access Token
accessTokenSecret*stringOAuth 1.0a User Access Token Secret
apiVersionstringX Ads API version number
doNotHashArray<string>Array of user data fields that should not be hashed
urlstringCustom base URL for the X Conversions API, ending in /
user_dataRecord<string, string>Mapping configuration for user identifiers
ipany | booleanClient IP, sent as the ip_address identifier. Resolves against { ingest, event }. Default: ["ingest.ip", "event.user.ip"]. false switches it off. A mapped user_data.ip_address wins.
userAgentany | booleanClient user agent, sent as the user_agent identifier. Resolves against { ingest, event }. Default: ["ingest.userAgent", "event.user.userAgent"]. false switches it off. A mapped user_data.user_agent wins.
* Required fields

Mapping​

Per-event rules under config.mapping. For the standard rule fields (consent, condition, data, batch, name, policy) see mapping.

PropertyTypeDescriptionMore
eventIdstringOverride the default conversion event ID for this event
valuestring | numberConversion monetary value (sent to X as a string)
currencystringHas no effect: the destination sends no currency to X (accepts an ISO 4217 code like USD or EUR)
number_itemsintegerNumber of items in the conversion
descriptionstringFree-text description of the conversion

Examples

Lead

A form submission is sent to X as a conversion with the SHA-256 hashed email as the identifier.

Event
{
  "name": "form submit",
  "data": {
    "string": "foo",
    "number": 1,
    "boolean": true,
    "array": [
      0,
      "text",
      false
    ]
  },
  "context": {
    "dev": [
      "test",
      1
    ]
  },
  "globals": {
    "lang": "elb"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "email": "user@example.com"
  },
  "nested": [
    {
      "entity": "child",
      "data": {
        "is": "subordinated"
      }
    }
  ],
  "consent": {
    "functional": true
  },
  "id": "ev-1700000901000",
  "trigger": "test",
  "entity": "form",
  "action": "submit",
  "timestamp": 1700000901000,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "express",
    "platform": "server"
  }
}
Out
sendServer("https://ads-api.x.com/12/measurement/conversions/o8z6j", "{\"conversions\":[{\"conversion_time\":\"2023-11-14T22:28:21.000Z\",\"event_id\":\"tw-o8z6j-o8z21\",\"identifiers\":[{\"hashed_email\":\"b4c9a289323b21a01c3e940f150eb9b8c542587f1abfd8f0e1cc1ffc5e475514\"}],\"conversion_id\":\"ev-1700000901000\"}]}", {
  "headers": {
    "Authorization": "<OAUTH_SIGNATURE>",
    "Content-Type": "application/json"
  }
})

Purchase

A completed order is sent to the X (Twitter) Conversions API with conversion value and the hashed email.

Event
{
  "name": "order complete",
  "data": {
    "value": 249.99,
    "currency": "EUR"
  },
  "context": {
    "shopping": [
      "complete",
      0
    ]
  },
  "globals": {
    "pagegroup": "shop"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "email": "jane@example.com"
  },
  "nested": [
    {
      "entity": "product",
      "data": {
        "id": "ers",
        "name": "Everyday Ruck Snack",
        "color": "black",
        "size": "l",
        "price": 420
      },
      "context": {
        "shopping": [
          "complete",
          0
        ]
      },
      "nested": []
    },
    {
      "entity": "product",
      "data": {
        "id": "cc",
        "name": "Cool Cap",
        "size": "one size",
        "price": 42
      },
      "context": {
        "shopping": [
          "complete",
          0
        ]
      },
      "nested": []
    },
    {
      "entity": "gift",
      "data": {
        "name": "Surprise"
      },
      "context": {
        "shopping": [
          "complete",
          0
        ]
      },
      "nested": []
    }
  ],
  "consent": {
    "functional": true
  },
  "id": "ev-1700000900000",
  "trigger": "load",
  "entity": "order",
  "action": "complete",
  "timestamp": 1700000900000,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "express",
    "platform": "server"
  }
}
Mapping
{
  "settings": {
    "value": "data.value"
  }
}
Out
sendServer("https://ads-api.x.com/12/measurement/conversions/o8z6j", "{\"conversions\":[{\"conversion_time\":\"2023-11-14T22:28:20.000Z\",\"event_id\":\"tw-o8z6j-o8z21\",\"identifiers\":[{\"hashed_email\":\"8c87b489ce35cf2e2f39f80e282cb2e804932a56a213983eeeb428407d43b52d\"}],\"conversion_id\":\"ev-1700000900000\",\"value\":\"249.99\"}]}", {
  "headers": {
    "Authorization": "<OAUTH_SIGNATURE>",
    "Content-Type": "application/json"
  }
})

Purchase with twclid

A purchase is sent to X with both the hashed email and the twclid click id for ads attribution.

Event
{
  "name": "order complete",
  "data": {
    "value": 89.99,
    "currency": "USD"
  },
  "context": {
    "twclid": [
      "23opevjt88psuo13lu8d020qkn",
      0
    ]
  },
  "globals": {
    "pagegroup": "shop"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "email": "buyer@co.com"
  },
  "nested": [
    {
      "entity": "product",
      "data": {
        "id": "ers",
        "name": "Everyday Ruck Snack",
        "color": "black",
        "size": "l",
        "price": 420
      },
      "context": {
        "shopping": [
          "complete",
          0
        ]
      },
      "nested": []
    },
    {
      "entity": "product",
      "data": {
        "id": "cc",
        "name": "Cool Cap",
        "size": "one size",
        "price": 42
      },
      "context": {
        "shopping": [
          "complete",
          0
        ]
      },
      "nested": []
    },
    {
      "entity": "gift",
      "data": {
        "name": "Surprise"
      },
      "context": {
        "shopping": [
          "complete",
          0
        ]
      },
      "nested": []
    }
  ],
  "consent": {
    "functional": true
  },
  "id": "ev-1700000902000",
  "trigger": "load",
  "entity": "order",
  "action": "complete",
  "timestamp": 1700000902000,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "express",
    "platform": "server"
  }
}
Mapping
{
  "settings": {
    "value": "data.value"
  },
  "data": {
    "map": {
      "user_data": {
        "map": {
          "twclid": "context.twclid"
        }
      }
    }
  }
}
Out
sendServer("https://ads-api.x.com/12/measurement/conversions/o8z6j", "{\"conversions\":[{\"conversion_time\":\"2023-11-14T22:28:22.000Z\",\"event_id\":\"tw-o8z6j-o8z21\",\"identifiers\":[{\"hashed_email\":\"484c39bfb51212665d9673805c112b5ba04cbf0460b6d3f00bcdc18b92afed66\"},{\"twclid\":\"23opevjt88psuo13lu8d020qkn\"}],\"conversion_id\":\"ev-1700000902000\",\"value\":\"89.99\"}]}", {
  "headers": {
    "Authorization": "<OAUTH_SIGNATURE>",
    "Content-Type": "application/json"
  }
})

When it fails

  • no identifier form: A form submit event without a user identifier cannot be sent to X: the push fails with missing-input instead of counting as delivered. Reported as failed with code missing-input.
  • no identifier order: A order complete event without a user identifier cannot be sent to X: the push fails with missing-input instead of counting as delivered. Reported as failed with code missing-input.

Failures​

A response outside the 2xx range, a network error, or no answer within 5 seconds fails the event: the push answers failed with the code transport (with the HTTP status) or timeout, the event goes to the dead-letter queue, and the collector logs one ERROR line. Any 2xx answer counts as delivered: the destination does not read the response body. Without pixelId, eventId or one of the four OAuth settings (consumerKey, consumerSecret, accessToken, accessTokenSecret) the destination does not start: every push answers failed with the code config, and the collector logs destination init failed. A rule with silent: true sends nothing.

Client IP and user agent​

The destination sends the client IP as the ip_address identifier and the user agent as the user_agent identifier by default. The ip and userAgent settings resolve against { ingest, event } and default to ["ingest.ip", "event.user.ip"] and ["ingest.userAgent", "event.user.userAgent"], so they fill in whenever the source provides them (see the config.ingest recipe on the Express source). A value your mapping sets for user_data.ip_address or user_data.user_agent wins. A value that resolves to nothing is not sent. Set either setting to false to turn it off, or to another mapping value to read it elsewhere.

The quickstart sets no config.consent, so X receives every event, whatever consent the event carries. To send only events with consent, add consent: { marketing: true } to config, next to settings (with several keys listed, one granted key is enough). An event without that consent is skipped or queued, depending on the collector's consentDenied. Server flows built by the CLI skip it and count it in skipped. With startFlow it waits in the destination's queue by default: a later event that carries consent does not release it, and only a walker consent command does, which then sends the waiting events of every user at once. Pass consentDenied: 'skip' to startFlow to skip such events instead (see Gate a destination with consent and consent-denied events on a server).

User identification​

The destination builds an identifiers array. Each identifier is a separate single-key object in the payload. At least one primary identifier is required. An event without one fails with missing-input.

Primary identifiers:

  • hashed_email: resolved from event.user.email or a user_data.email mapping. The email is normalized (trimmed, lowercased) and SHA-256 hashed before sending. Set doNotHash: ['email'] if you are pre-hashing upstream: the email is then sent trimmed and lowercased, but not hashed.
  • hashed_phone_number: resolved from event.user.phone or a user_data.phone mapping, trimmed and SHA-256 hashed as mapped. X expects the number in E.164 format (+491701234567), so map it in that form: the destination does not remove spaces, brackets or dashes. Use doNotHash: ['phone'] to skip hashing: the number is then sent trimmed, but not hashed, so use it only for a value you hash upstream.
  • twclid: X click ID (pass-through, not hashed). The session source reads it from the landing page URL into its session start event only, so carry it to your conversion events yourself (the snippet reads context.twclid):
"settings": {
  "pixelId": "o8z6j",
  "eventId": "tw-o8z6j-o8z21",
  "consumerKey": "$secret.TWITTER_CONSUMER_KEY",
  "consumerSecret": "$secret.TWITTER_CONSUMER_SECRET",
  "accessToken": "$secret.TWITTER_ACCESS_TOKEN",
  "accessTokenSecret": "$secret.TWITTER_ACCESS_TOKEN_SECRET",
  "user_data": {
    "twclid": "context.twclid"
  }
}

Secondary identifiers: ip_address and user_agent are optional and sent unhashed (see Client IP and user agent).

Every other key in user_data (for example phone_number, hashed_email or em) is dropped without a log line, and a list mapped to email is ignored in favour of event.user.email.

Per-event overrides​

The default eventId from settings applies to all events. Override it per event via mapping to route different events to different pre-registered conversion events:

"mapping": {
  "order": {
    "complete": {
      "settings": {
        "eventId": { "value": "tw-o8z6j-purchase01" },
        "value": "data.value",
        "number_items": "data.count"
      }
    }
  }
}

Browser deduplication​

This destination sends the event's id as conversion_id. If the X Pixel in the browser tracks the same conversion, use the conversion event you created for the pixel as eventId here, and give the pixel the walkerOS event id as its conversion_id: X counts a conversion that the pixel and the Conversions API send with the same conversion_id once (web conversions). walkerOS has no X Pixel destination, so the pixel side is set up outside walkerOS.

💡 Need implementation support?
elbwalker offers hands-on support: setup review, measurement planning, destination mapping, and live troubleshooting. Book a 2-hour session (€399)