Integration guide

Connect a business in under an hour

Your dashboard's business page generates both snippets below with the real keys filled in. This page is the reference.

Step 1 — Connect the channels (dashboard)

Open the business → Channel credentials. Paste the client's Meta pixel id + CAPI access token (Events Manager → Settings → Conversions API → Generate access token) and/or the TikTok pixel code + access token (TikTok Ads Manager → Tools → Events → Web Events → Settings), and/or the GA4 measurement id + Measurement Protocol API secret (Google Analytics → Admin → Data streams → your stream → Measurement Protocol API secrets). GA4 receives the same events (Purchase → purchase, Lead → generate_lead) so the client's analytics tell the whole story; note GA4 fills analytics — Google Ads optimisation is a separate Google mechanism. Tokens are encrypted into the vault the moment you save — they are never displayed again, only their last 4 characters. Optionally add the public pixel ids so your site can also run the standard browser pixels.

Step 2 — Browser events (one script tag)

Add the helper to every page, then call synxTrack when something happens. It returns the event_id — keep it; your server needs it in Step 3.

<script src="https://YOUR-SYNX-HOST/p.js?b=pub_xxxxxxxxxxxxxxxx"></script>
<script>
  // On purchase, checkout, signup… — returns the event_id:
  var id = synxTrack('Purchase', {
    custom_data: { value: 79, currency: 'USD', order_id: '1001' }
  });
  // Send `id` to your server with the order, e.g. in a hidden field or fetch.
</script>

The helper automatically attaches the _fbp, _fbc and _ttp cookies when they exist, and Synx captures the visitor's IP address and browser user agent from the connection — IP, user agent, click ids and hashed email/phone are exactly the signals Meta scores as Event Match Quality, so richer events match better and attribute more accurately. It never throws — tracking can never break your page.

Step 3 — Server events (one API call)

From your server, send the same event with the same event_id and the customer data only the server knows (email, phone, order). Synx hashes email/phone before anything is stored or forwarded.

curl -X POST https://YOUR-SYNX-HOST/v1/events \
  -H 'x-api-key: synx_••••••••••••••••' -H 'content-type: application/json' \
  -d '{
    "event_name": "Purchase",
    "event_id": "<THE_ID_FROM_STEP_2>",
    "source": "server",
    "user": { "email": "buyer@example.com", "phone": "+85512345678" },
    "custom_data": { "value": 79, "currency": "USD", "order_id": "1001" }
  }'
→ 202 { "accepted": true, "event_id": "…", "deduplicated": false }

The 202 returns immediately; forwarding happens in the background and failures are retried automatically (up to 3 times, with backoff). If your server cannot call us at purchase time, browser-only events still forward — you just lose the server-only data.

Integrations — webhook-in & offline sales

1
A sale happens
Logged in the dashboard, or posted by your POS/CRM.
→
2
Synx protects it
Phone & email are SHA-256 hashed before anything is sent.
→
3
Meta + TikTok receive it
As a Purchase event, to both platforms at once.
→
4
It shows as “Server”
In Events Manager within ~30 minutes, credited to the campaign.

Webhook-in. Any system that can send a webhook — a POS, a CRM, a shop platform, a spreadsheet automation — can post a sale straight to Synx with the business's server API key. A flat payload is enough:

curl -X POST https://YOUR-SYNX-HOST/v1/webhooks \
  -H 'x-api-key: <YOUR_API_KEY>' -H 'content-type: application/json' \
  -d '{"order_id":"1001","value":79,"currency":"USD",
       "phone":"+85512345678","email":"buyer@example.com",
       "channel":"telegram"}'

The order_id becomes the event id (wh_1001) — so if the system retries or double-posts, the sale is still counted exactly once. channel can be telegram, messenger, phone or store; it sets the action source Meta expects for that kind of sale. The full event shape from Step 3 also works here unchanged.

Offline sales. Many businesses close the sale in a chat or a call, days after the ad click. Log those sales and Meta can match them back to the click — that's what turns "website conversions" into real revenue attribution. Two ways: the Log an offline sale form on each business in your dashboard (phone number + amount is enough), or automatically via the webhook above. Send sales the same day when you can — recent sales match best. The customer's phone number is the key: it is SHA-256 hashed before anything leaves Synx, exactly like every other event.

How deduplication works

Meta and TikTok count an event once when the browser and server copies share an event_id — but only if both copies actually arrive, and only once each. Synx enforces the same rule on our side first: the first copy of a business + event_id + event_name is forwarded to each connected channel; the second copy is stored, marked deduplicated, and never re-sent. Your dashboard shows both copies, so you can prove the pairing worked. If you don't supply an event_id, Synx generates one (synx_…_Purchase) — but then browser and server copies cannot be paired, so always share the id for purchases.

Event reference

FieldNotes
event_nameStandard: Purchase, Lead, CompleteRegistration, InitiateCheckout, AddToCart, ViewContent, AddPaymentInfo — or any custom name (passed through; TikTok standard names are mapped automatically, e.g. Purchase → CompletePayment).
event_idOptional but strongly recommended — the dedupe key. Share it between the browser and server copies.
source"server" (default with an API key) or "browser" (forced for public-key posts).
user.email / user.phoneSHA-256 hashed at intake (phone normalised to digits with country code). Never stored or forwarded raw.
user.external_id / telegram_idHashed into Meta/TikTok external_id. telegram_id folds into external_id automatically.
user.ip / ua / fbp / fbc / ttclidMatch-quality signals, forwarded as-is to the platforms.
custom_datavalue, currency, order_id plus any extra keys — passed through to both platforms.

What “healthy” means

Each business gets a health light from its own event log: events flowing and forwards succeeding · silent for 26+ hours, or forward errors rising · silent for 3+ days, or most forwards failing. Silence after activity, or a forward failure rate above 50% in 24h, raises an alert on your dashboard (and to the platform operator on Telegram, when configured). Health comes from Synx's own logs — we never read a client's Events Manager.