Track campaign, route, and playbook links

Tracked links connect a click with the message that created it, the customer profile, a session, reporting, and later activity on your site.

Hellotext can create these links in campaign, journey, playbook, and Inbox messages. For the context to continue after the redirect, the destination site must preserve the session and explicitly track later activity.

What Hellotext does when the customer clicks

In the editor, use Insert short link, the chain icon in the bottom toolbar. Paste the complete destination into Create a shortlink and select Add short link. Typing a URL as text is not the same as inserting it with this tool.

The following real draft in Settings → Templates, Message mode with an SMS preview, helps you recognize the control. Its URL is still text: no link was created, the template was not saved, and the message was not sent.

The editor creates a reusable business link. When Hellotext prepares a message for a recipient, it creates the personalized link and its session, with an address such as hello.link/XXXXXX or the business’s verified custom domain. Opening the editor link or a preview does not demonstrate a click by that recipient: those addresses can redirect in preview mode without the sent message’s context.

When the customer opens the personalized link, Hellotext:

1. Redirects to the original URL with hello_session and the applicable UTM parameters.
2. Queues click recording; the redirect can finish before processing does.
3. When processing an accepted click, records short_link.clicked for the corresponding profile and message, preserves its source references, and updates the available counters and reports.

Hellotext filters previews it identifies as bots, both at redirect time and during request processing. This does not infallibly identify every person: a recorded click represents interaction with the link, not verified identity, a purchase, or guaranteed conversion.

Do not send short_link.clicked manually from your integration. Hellotext creates it when processing the click; duplicating it from the site would distort activity and counters.

Parameters received by the destination site

The redirected URL can look like this; the values are illustrative:

https://shop.example.com/products/everyday-sneakers?hello_session=SESSION_ID&utm_source=hellotext&utm_medium=sms&utm_campaign=example_campaign

The parameters have different purposes:

• hello_session contains the ID of the session associated with the personalized link. It is not a private API token or authorization to send messages.
• utm_source identifies the traffic source; its value is normally hellotext.
• utm_medium identifies the message technology, such as sms, when available.
• utm_campaign uses the campaign or journey’s configured UTM token, or the playbook code. Do not assume it is the API object’s public ID; it may be absent when that source does not apply.

The current parameter is hello_session. Do not use or look for hellotext_session.

Hellotext preserves the destination fragment and other parameters. If a UTM key generated by Hellotext already exists, its generated value replaces the previous one; avoid destinations that already contain hello_session or duplicate keys. Do not remove these parameters in an intermediate redirect or substitute another person’s session ID.

How the session continues on the site

In the published Hellotext.js SDK, version 2.6.0, the session comes first from hello_session in the URL, then from a session supplied in configuration, then from the cookie. If none exists and autoGenerateSession is enabled, another session is generated.

Initialize the library before your router or storefront code removes the parameters. initialize() is asynchronous: await its completion. This example assumes Hellotext.js is already loaded and uses the public Business ID, without a private token:

(async () => {
  const redirectedSession = new URL(window.location.href)
    .searchParams.get("hello_session");

  await Hellotext.initialize("HELLOTEXT_BUSINESS_ID");
  console.log({ redirectedSession, session: Hellotext.session });

  const response = await Hellotext.track("page.viewed");
  if (response.failed) {
    console.error(await response.json());
  }
})().catch((error) => {
  console.error(error);
});

When hello_session arrives, compare it with Hellotext.session after initialization. The SDK retains the session in a cookie when the browser allows writing it and attempts to acknowledge receipt to the server. Seeing a local ID does not prove that acknowledgement or an event has been processed. If storage is blocked, check continuity again when navigating or reloading.

Hellotext.js does not automatically track page.viewed during initialization. Make one explicit call per real view. In a single-page application, initialize once and, after each navigation you want to measure, call Hellotext.track("page.viewed", { url: window.location.href }) once; avoid duplicating another integration’s recording. If the page represents a product, also track product.viewed with the corresponding product. The URL alone does not provide all catalog data.

See Tracking unidentified customers for the session and identity lifecycle, and check examples against the SDK version you use.

Context by message source

The same mechanism preserves different references depending on where the message was created:

• Campaign: the campaign, broadcast, and recipient’s message.
• Journey: the journey, step, and executed message.
• Playbook: the playbook and message generated for the recipient.
• Inbox: the profile and conversation message, even when there is no campaign or automation report.

Hellotext retains these references; they are not all transmitted as separate URL parameters. A utm_campaign alone does not replace the session or prove a message is eligible for attribution.

Do not manually reuse a personalized message link for other customers or sends. If someone forwards it, it retains the original recipient’s context; you cannot assume the person opening it is that same recipient. Add the destination through the editor tool and let Hellotext prepare each message’s context.

How later events are connected

The click lets you continue a session that may already have been created during message preparation. To understand what happened next, track relevant actions:

• Your site explicitly calls Hellotext.js for navigation, product views, and cart changes that another integration does not already track.
• Your backend tracks orders, payments, cancellations, shipments, and deliveries using reliable system data.
• When the customer becomes known, the session must be associated with the correct profile in the same business. Do not reassign it based only on a forwarded URL.

If checkout happens on another domain or application, retain Hellotext.session in your checkout context and pass it to your backend before losing it. A cookie is not automatically shared between different domains. Tracking a profile without its session does not by itself retain all earlier navigation, and supplying both IDs does not automatically create a valid association if one did not exist.

Include the original event time when recording delayed activity, using the format supported by your endpoint. Distinguish received from a processed event and an attributed sale. Neither a click nor a session grants consent to communications.

Do not send the same event from Hellotext.js and your backend or immediately repeat a request with an uncertain outcome. See Tracking events and External tracking.

Clicks, reporting, and attribution

Processed clicks can appear in profile activity and campaign, journey, or playbook reports when available. The link counter includes accepted repeated clicks; it does not equal unique people. Message-level unique-click metrics also do not prove how many different people opened a forwarded URL. A successful redirect does not guarantee an immediately updated counter.

An eligible click can provide active attribution evidence inside the default seven-day window from the click. An eligible delivery can provide passive evidence inside the default 24-hour window. These windows can be configured by business; they do not represent automatic link or cookie expiration.

Hellotext also evaluates:

• Whether the customer, business, and order are identified correctly.
• Whether the click belongs to a message delivered to that customer and occurs after delivery.
• Whether the source is usable and, for a campaign, had already started when the purchase occurred.
• Whether the click precedes the purchase and the purchase falls inside the applicable window, using original timestamps even if processing happens later.
• Whether another valid source has higher precedence.

Keeping hello_session helps connect context, but does not guarantee that every later event receives that source or every purchase is attributed. See How we attribute sales for complete windows, precedence, and examples.

Verify the implementation

In an authorized test environment, use a recognizable profile and message, with the appropriate channel and consent:

1. Insert the destination with the editor tool and distinguish the draft link from the recipient message’s personalized link.
2. If you perform an authorized test send, open that message’s link; an editor preview does not test the same flow.
3. Confirm that intermediate redirects preserve hello_session and the expected UTM values without duplicating or overwriting the session.
4. Await initialize(), compare Hellotext.session with the received ID, and explicitly track page.viewed once.
5. Check profile activity after processing and distinguish total clicks from unique metrics.
6. Review the source report when available, using the correct period and channel.
7. Record only activity needed for the test and verify the object, customer, session, and original time; check attribution separately.
8. Confirm another integration did not record the same activity or an extra manual short_link.clicked.

Troubleshoot common problems

• The click appears, but later activity does not: preserve hello_session until initialization, await the library, and verify explicit tracking calls and their processing.
• The session changes on arrival: review redirects, duplicate keys, domains, blocked storage, and initialization order. Do not confuse a local ID with a confirmed profile association.
• The page view appears without a product: track product.viewed with the corresponding product.
• The click does not appear in the report: check that you opened the correct personalized message link rather than the draft link or a preview; consider bot filtering, processing, and the report period.
• The purchase is not attributed: review identity, business, order, delivery, original times, window, and precedence. A UTM value or session alone is not enough.

If signals are missing, use Troubleshoot missing signals or activity.

Related guides

• Tracked links
• Message editor overview
• Tracking unidentified customers
• External tracking
• How we attribute sales
• Custom domain for short links