On this page

Developer guide

Know which ads bring customers — and answer them on your site

One script tag records where each visitor came from and what they did, sends your conversions to Meta, and runs an AI assistant that can look up orders through your own system — without ever touching your database.

Steps 1 and 2 are all most sites need. Your site key and site secret are in Loudpilot under Website → Loudpilot Tag.

Install the tag

Put this in the <head> of every page. It loads asynchronously and never slows the page down.

html
<script async src="https://loudpilot.app/t.js" data-site="lp_3fK9aQ2xZ1bT"></script>
  • WordPress — a “header and footer scripts” plugin, or your theme’s header.php.
  • Shopify — Online Store → Themes → Edit code → theme.liquid, before </head>.
  • Tilda, Wix, Webflow — Site settings → Custom code → Head.
  • Google Tag Manager — a Custom HTML tag on All Pages.
  • React, Next.js, Vue — the same tag in the root layout. Page changes inside a single-page app are tracked automatically.

If inline scripts call loudpilot() before the tag has loaded, add the queue line first — calls made before loading are kept and sent in order:

html
<script>window.loudpilot=window.loudpilot||function(){(loudpilot.q=loudpilot.q||[]).push(arguments)}</script>
<script async src="https://loudpilot.app/t.js" data-site="lp_3fK9aQ2xZ1bT"></script>
AttributeTypeDescription
data-siterequiredYour site key (public, safe in the page).
data-consent"required"Record nothing until consent is given — see Cookie consent.
data-forms"off"Do not turn forms into Lead events automatically.

In Loudpilot, set Your domains so events are accepted only from your sites (subdomains included).

What is tracked by itself

EventTypeDescription
PageViewevery pageIncluding page changes in single-page apps.
ContactclicksLinks to tel:, mailto:, WhatsApp (wa.me), Telegram (t.me) and Viber. properties.method says which.
Leadform submitAny form with an e-mail or phone field (not login forms with a password). The e-mail / phone also identify the person.

Each visit records where it came from: utm_* parameters, the ad click id (gclid, fbclid, ttclid, msclkid), or the referring site (Google search, Instagram, ChatGPT…). A new ad click starts a new visit; 30 minutes without activity end one. Add data-lp-ignore to a form to skip it.

Track conversions

Call it where the action happens — usually on the thank-you or order-confirmation page.

js
loudpilot('track', 'Purchase', { value: 120, currency: 'GEL', order_id: '1001', content_ids: ['rose-box'] })
loudpilot('track', 'Schedule')                       // a booking
loudpilot('track', 'CompleteRegistration')           // a sign-up
loudpilot('track', 'quiz_finished', { score: 8 })    // your own event

Use Meta’s standard names — they go to Meta as they are: PageView, ViewContent, Search, AddToCart, AddToWishlist, InitiateCheckout, AddPaymentInfo, Purchase, Lead, CompleteRegistration, Contact, Schedule, SubmitApplication, Subscribe, StartTrial, FindLocation, Donate, CustomizeProduct. GA4 names work too (purchase, generate_lead, sign_up, add_to_cart, begin_checkout). Other names are custom events (letters, digits and _ up to 40).

PropertyTypeDescription
valuenumberMoney value; reports add it up as revenue.
currencystringISO 4217, e.g. GEL, USD.
anything elseJSONKept with the event (up to 3 KB) and sent to Meta as custom_data — order_id, content_ids, …

Reports count Lead, Contact, CompleteRegistration, Schedule, SubmitApplication, Subscribe and StartTrial as leads, and Purchase as a sale.

Identify people

When you know who the visitor is — they logged in or left their details — tell the tag. It helps match sales from your server to the ad that brought the person, and Meta to match the conversion.

js
loudpilot('identify', { email: 'nino@example.com', phone: '+995599123456', name: 'Nino' })

Loudpilot keeps only a SHA-256 hash of the e-mail and phone (what Meta matches on) and a masked form for your reports (ni***@example.com). For logged-in customers in the chat, also pass user_id and user_hash — see Signed-in customers.

The visitor id

To tie an order in your system to the visit and the ad, send the visitor id with it. Three ways to get it:

  • Forms — add <input type="hidden" name="lp_visitor_id">; the tag fills it in. Your CRM receives it with the lead.
  • Your server — read the _lp_id cookie from the request (it is on your own domain).
  • JavaScript — loudpilot('visitorId', (id) => …).

Without it, Loudpilot still finds the person by user id, e-mail or phone if they were identified on the site before.

Server-side events

Report what happens outside the browser — an order paid by bank transfer, a deal won in your CRM, a call booked by phone. Loudpilot credits it to the person’s latest visit, so the sale shows up under the ad that brought them.

POSThttps://loudpilot.app/api/tag/v1/events

Authenticate with the site secret as a bearer token (simplest; also works from Zapier, Make and n8n), or sign the raw body like our requests to you and send X-Loudpilot-Signature. From your server only.

BodyTypeDescription
sitestring, requiredYour site key.
eventsarray, required1–100 events.
events[].namestring, requiredPurchase, Lead … (see Track conversions).
events[].event_idstringYour id (e.g. order-1001). The same id twice is recorded once — safe to retry.
events[].visitor_idstringThe _lp_id cookie / lp_visitor_id field.
events[].user_idstringYour customer id, if they signed in on the site.
events[].email, phonestringUsed to find the person; stored hashed.
events[].value, currencynumber, stringMoney value and ISO currency.
events[].timenumberUnix seconds when it happened (default: now).
events[].url, ipstringPage and client IP, if you have them (better Meta matching).
events[].propertiesobjectAnything else, up to 3 KB.
curl -X POST https://loudpilot.app/api/tag/v1/events \
  -H "Authorization: Bearer $LOUDPILOT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"site":"lp_3fK9aQ2xZ1bT","events":[{"name":"Purchase","event_id":"order-1001","visitor_id":"8f3a…","email":"nino@example.com","value":120,"currency":"GEL"}]}'
Response
{
  "results": [
    {
      "event_id": "order-1001",
      "status": "recorded",
      "matched": true
    }
  ]
}

status is recorded, duplicate (that event id was already recorded) or invalid (unusable name). matched says whether the person was found; unmatched events still count, without a source. Errors: 401 unauthorized, 404 unknown_site, 400 invalid_request, 429 rate_limited.

Meta Conversions API

Turn on Send conversions to my Meta pixel in Loudpilot and enter the pixel (dataset) id. Conversions from the browser, your server and the chat go to Meta from Loudpilot’s server within a minute — with the click id, hashed e-mail / phone, IP and browser, so Meta can match them even when the pixel is blocked. It uses your connected Meta ad account, or a Conversions API token you paste (Events Manager → Settings → Generate access token).

No double counting. Meta counts an event once when the pixel and the server send the same event id. If your site does not send these events to the pixel itself, turn on Also send them through the pixel — the tag fires fbq('track', …) with the same id. If your site already sends, say, Purchase to the pixel, untick Purchase in Events to send.

The assistant

Switch it on in Loudpilot under Inbox → Assistant; the tag shows the chat button on every page. It answers from the instructions and facts you give it (it can write a first version from your website), in the languages you choose. Red-flag topics, a request for a person, or anything it cannot answer go to your team — by e-mail and Telegram — and you answer in Inbox → Website chat; the visitor sees your reply in the same chat.

js
loudpilot('chat', 'open')   // e.g. from your own "Ask us" button
loudpilot('chat', 'close')
loudpilot('chat', 'hide')   // no chat button on this page (checkout…)
loudpilot('chat', 'show')

Without your data endpoint the assistant answers general questions and hands questions about orders and accounts to your team.

Signed-in customers

When the visitor is logged in on your site, tell the tag who they are, with a hash only your server can make. Lookups marked For signed-in customers only (“my orders”, “my bookings”) are then offered to the assistant, and Loudpilot sends your endpoint that customer id — the assistant cannot choose or change it, so it can never ask about someone else.

user_hash = HMAC-SHA256 of the user id with your site secret, hex. Compute it on your server; never put the secret in the page.

import { createHmac } from 'node:crypto'

const userHash = createHmac('sha256', process.env.LOUDPILOT_SECRET).update(String(user.id)).digest('hex')
// Render into the page:
// <script>loudpilot('identify', { user_id: '${user.id}', user_hash: '${userHash}', name: '${user.firstName}' })</script>

A wrong or missing hash is ignored: the visitor is treated as not signed in.

Your data endpoint

One HTTPS endpoint on your server answers the lookups you list in Loudpilot (order status, my orders, a booking…). When the assistant needs one, Loudpilot calls it — signed with your site secret — and the assistant reads only what you return.

Loudpilot → your endpoint
POST https://api.yourshop.ge/loudpilot
Content-Type: application/json
X-Loudpilot-Action: order_status
X-Loudpilot-Signature: t=1792570000,v1=9a3f…

{
  "action": "order_status",
  "params": {
    "order_number": "A-1001",
    "email_or_phone": "nino@example.com"
  },
  "customer": null,
  "conversation_id": "cmc4…",
  "site": "lp_3fK9aQ2xZ1bT",
  "test": false
}
FieldTypeDescription
actionstringThe lookup’s name as you set it in Loudpilot.
paramsobjectExactly the details you listed for that lookup, as the visitor gave them (strings, up to 200 characters).
customerobject | null{ id, verified: true } for a signed-in customer (verified with user_hash); null otherwise.
conversation_idstringFor your logs.
testbooleantrue for test requests and demo-shop chats.
Your answerTypeDescription
200 + JSONfoundOnly what the customer may see: status, dates, tracking link. Keep it small (up to 100 KB).
404not foundNot found — also when the second detail does not match. Never say which detail was wrong.
401 / 403not allowedBad signature, or a lookup that needs a signed-in customer without one.
anything elseunavailableThe assistant apologises and offers a person.

8-second timeout; redirects are not followed.

import express from 'express'

// X-Loudpilot-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256(secret, "<t>.<raw body>")>
export function verifyLoudpilot(rawBody, header, secret) {
  const m = /t=(\d+),v1=([a-f0-9]{64})/.exec(header ?? '')
  if (!m || Math.abs(Date.now() / 1000 - Number(m[1])) > 300) return false
  const expected = createHmac('sha256', secret).update(`${m[1]}.${rawBody}`).digest('hex')
  return timingSafeEqual(Buffer.from(expected), Buffer.from(m[2]))
}

const app = express()
app.post('/loudpilot', express.raw({ type: 'application/json' }), async (req, res) => {
  const raw = req.body.toString('utf8')
  if (!verifyLoudpilot(raw, req.get('x-loudpilot-signature'), process.env.LOUDPILOT_SECRET)) return res.status(401).end()
  const { action, params, customer } = JSON.parse(raw)

  if (action === 'order_status') {
    const order = await db.orders.findByNumber(params.order_number)
    // The second detail must match the order — otherwise it is simply "not found".
    const given = params.email_or_phone.trim().toLowerCase()
    if (!order || (given !== order.email.toLowerCase() && digits(given) !== digits(order.phone))) return res.status(404).json({})
    return res.json({ status: order.status, delivery: order.deliveryDate, tracking_url: order.trackingUrl })
  }
  if (action === 'my_orders') {
    if (!customer?.verified) return res.status(403).json({})
    const orders = await db.orders.recentForUser(customer.id, 5)
    return res.json({ orders: orders.map((o) => ({ number: o.number, status: o.status, total: o.total })) })
  }
  res.status(404).json({})
})

const digits = (s) => String(s ?? '').replace(/\D/g, '')

How private data stays private

  • No database access. Loudpilot never connects to your database and never receives credentials. The assistant can only ask your endpoint the lookups you listed; your code decides what to return.
  • Identity comes from your website, not from the chat. “My orders” lookups get the customer id from your login (verified with user_hash). Whatever the visitor types, the assistant cannot pick another id.
  • Two details for anonymous lookups. Without login, ask for something only the customer knows alongside the number (the e-mail or phone on the order) and check both. Answer “not found” for any mismatch.
  • No guessing. Each chat may make at most 15 lookups an hour, and each visitor IP at most 30 messages a minute.
  • Minimum data. Return what the customer needs to read — not addresses, full card numbers or internal notes. Loudpilot logs which lookups ran and whether they succeeded, never the data they returned.
  • Signed both ways. Every request to you is signed with your site secret and time-stamped (reject anything older than 5 minutes).
  • Red flags go to people. Refunds, complaints, legal or medical questions — whatever you list — are handed over at once.

Testing

  • Demo shop — Website → Loudpilot Tag → Try it in a demo shop opens a pretend store with your tag: add to cart, pay, leave a contact, sign in as a demo customer (user_id loudpilot-demo-customer) and talk to the assistant, even before it is switched on. Its visits are marked as tests and stay out of the reports.
  • Test requests — each lookup in Inbox → Assistant has Send a test request: it calls your endpoint exactly as the assistant would (with test: true) and shows your answer.
  • Live events — Website → Loudpilot Tag → Latest events shows every event within seconds, and whether it went to Meta.

Site secret

Shown to owners and admins in Website → Loudpilot Tag → Site secret (lpsec_…). It signs user_hash, authenticates server-side events and signs Loudpilot’s calls to your endpoint. Keep it in your server’s environment (LOUDPILOT_SECRET), never in the page or an app. New secret replaces it at once — update your server at the same time.

Signatures

X-Loudpilot-Signature: t=<unix seconds>,v1=<hex>, where the hex is HMAC-SHA256 of <t>.<raw body> with your site secret. Compute it over the raw bytes, before parsing JSON. The same scheme signs server-side events you send us.

import { createHmac, timingSafeEqual } from 'node:crypto'

// X-Loudpilot-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256(secret, "<t>.<raw body>")>
export function verifyLoudpilot(rawBody, header, secret) {
  const m = /t=(\d+),v1=([a-f0-9]{64})/.exec(header ?? '')
  if (!m || Math.abs(Date.now() / 1000 - Number(m[1])) > 300) return false
  const expected = createHmac('sha256', secret).update(`${m[1]}.${rawBody}`).digest('hex')
  return timingSafeEqual(Buffer.from(expected), Buffer.from(m[2]))
}

Limits

WhatTypeDescription
Browser events600 / minute per IPBots and link previews are ignored.
Server-side events1,200 requests / minute per siteUp to 100 events per request.
Chat messages30 / minute per IP, 20 / minute per chatUp to 2,000 characters each.
Data lookups15 / hour per chat8-second timeout, 100 KB answers.
Meta Conversions APIwithin a minuteEvents older than 7 days are not accepted by Meta.
Assistant1 credit per conversationCharged on its first answer; a person answering costs nothing.

Questions or a platform we should cover? Write to us.