Skip to main content
When the engine decides to speak, it places one card in a short-lived queue for that visitor. The page collects it with a small poll and reports what happened. You can let NextIntent’s card snippet render it, render it yourself from a browser event, or hand it to a popup tool.

The card route

GET /card answers 200 { card } exactly once while a card is waiting, then 204 until another is placed. The card is read with a single atomic take, so a refresh cannot show it twice. A card waits three minutes; a visitor who left never sees a stale one. Both routes are origin-gated. The card object:
cta_path is always a same-origin path; the engine never emits an absolute URL. cta_label and cta_path are null when there is no link.

The ack

event is one of shown, clicked, dismissed, handed_off, not_shown. Send shown when the sentence is on the screen. This is the report that makes the visitor count as helped; without it, no order can be credited to the moment. Send clicked when the link is followed and dismissed when the visitor closes it. handed_off means the moment was given to a popup tool or to the site’s own code and nothing has been confirmed yet; not_shown means it never was. An optional detail object may carry via (callback, dom, developer, card, fallback_card), provider, campaign_id and reason, each a short token of at most 64 characters.

The poll

The reference snippet starts 12 seconds after the visitor id is known, polls every 6 seconds while the tab is visible, backs off, and stops after 15 minutes or once a card has been delivered. It remembers delivery in sessionStorage so a visitor sees one card per session. Follow the same shape if you write your own: never poll a hidden tab, never poll after delivery.

Getting the visitor id

The SDK keeps the visitor id in the frame it opened from iframe.nextintent.ai. Ask the frame with postMessage({ action: 'find', source: '<nsp>/user_id', id, channel }, ...) where nsp and channel come from the frame’s src query string; the reference snippets show the exact exchange. Accept replies only from https://iframe.nextintent.ai.

The event

Whatever the output setting, the reference snippet fires a DOM event when a card is delivered:
With output set to event in the facts sheet, nothing is drawn. The snippet sends handed_off when the event fires and waits for your code to confirm. Confirm with either of these once your element is on the screen:
Then the snippet sends shown with via: developer. If nothing confirms within 8 seconds it sends not_shown, and the moment is never counted or billed. With output set to card, the event still fires and the card is drawn. Confirming is not optional. A site on event output that has handed off at least one moment and never once confirmed is moved to the hand-off basis for the rest of the month: every handed_off counts as helped and its order is billed, and money.credited_basis on the store view reads handoff with money.confirmation carrying the tally and flagged_since. The same happens to any site where fewer than half of ten or more hand-offs confirm, or fewer than half of ten or more cards ack shown. Ledger rows carry basis: "confirmed" or "handoff". Call NextIntent.shown(id) as soon as your element is visible and the site stays on the confirmed basis. With output set to popup, the snippet reads the popup object from the facts sheet ({ provider, campaign_id, code_campaign_id }; the Shopify app writes it from Settings, and a theme may override it with window.NextIntentOutput) and asks the tool to show that campaign: OptiMonk (OptiMonk.Api.campaigns.show), Justuno (juapp('trackFunnel', 'nextintent:' + id)), Privy (Privy('show', id)), Wisepops (wisepops('event', 'nextintent:' + id)), Klaviyo (_klOnsite.push(['openForm', id])). code_campaign_id is used when the card is about a declined code. The snippet sends handed_off first and shown only on confirmation. Klaviyo confirms through its klaviyoForms document event (type: open), Wisepops through wisepops('listen', 'after-popup-display'). For OptiMonk, Justuno and Privy, and as a fallback for the other two, the snippet watches the page for up to 8 seconds for the tool’s popup element to appear and be visible, then sends shown with via: dom. If nothing appears it sends not_shown with reason: timeout and draws nothing of its own. If the tool is absent from the page, or no campaign id is set, the snippet draws its own card and sends shown with via: fallback_card.

Detected tools

Once a day the snippet looks for the five tools’ globals on the page and reports them:
They land on the facts sheet as detected_tools with detected_at, read-only: a PATCH cannot set them. The Shopify app offers “Your popup tool” only when this list is not empty.

The Klaviyo event

When the facts sheet has klaviyo.send_moments: true and Klaviyo’s script is on the page, the snippet, after a card is delivered and once per moment, calls Klaviyo’s onsite object (klaviyo, or the legacy _learnq) only when isIdentified() is true. It never passes an email or any identifier.
  • track('NextIntent moment', props) with reason, reason_key, sentence (or null), shown (boolean), output, page_path, cart_total, moment_id, and $value set to the cart total when there is one.
  • identify({...}) with the profile properties NextIntent last reason, NextIntent last sentence, NextIntent last moment at (ISO time).
The reason labels are the engine’s own (src/reason_of.js): for example “Choosing a size or color”, “Hunting for a discount code”, “Shipping cost or speed”. The card route now returns reason_key, reason_label, cart_total and page alongside the sentence so the snippet has them. Merchant guidance, including the template block, is on Klaviyo: the reason in your email.

Rendering your own card

Keep three rules: put the text in with textContent (never HTML), accept cta_path only when it starts with /, and send the shown ack when the element is on the screen. The sentence must never be shown twice in a session.