Skip to main content
Most problems on a directly integrated site come down to one of six things: the origin, the switches, the sheet, the ack, the order feed, or the key. Each section says what you see, what it usually is, and where to look. Shopify-specific problems (the app embed, billing, the bill against Money) are in Troubleshooting for Shopify.

​
The site never shows connected

state.deployed is true, state.connected stays false.
  1. Open a page of the site with the browser’s developer tools on the Network tab. Find the request to sdk.nextintent.ai/<site_id>/settings. A 403 means the page’s origin is not on the allowed list; a 418 means enabled is false.
  2. Compare the page’s exact origin (scheme, host, port) with urls on the site record. https://acme.com and https://www.acme.com are different origins; both should be on the list.
  3. If settings answered 200, look for the websocket to the collector. A refused handshake with token_stale means the site’s origins were changed and this page loaded a cached settings answer; reload once.
  4. Nothing at all: the tag is not on this page. Run GET /v1/sdk/{id}/install-check.

​
No moments appear

Connected is true, Moments is empty after a day of traffic.
  • A visitor is not judged in the first 30 seconds of a visit or the first 20 seconds on a page, and never while typing. Very short visits produce no moments.
  • The capture toggles: with behavioral or scroll off the idle rule has little to work with. Turn them on.
  • The site type: a site classed as Personal or Nonprofit has few commercial paths, so “dwelling on a high-intent page” rarely fires. Check vertical.
  • The moments list defaults to 50 newest; pass verdict=engage to see only the engages, and read the quiet ones to see what the engine is leaving alone and why.

​
A sentence never shows

Engages appear in Moments with a sentence, nothing appears on the page.
  1. shadow must be false and card_enabled true. Watch mode records sentences and shows none.
  2. The facts sheet: an engage with no sentence, or a sentence the sheet cannot back, places nothing. Read the moment; if proposed is present and delivery says withheld, the sheet is missing the fact.
  3. The card snippet: it starts polling 12 seconds after the visitor id is known and only while the tab is visible. A test that navigates away in 10 seconds never collects the card.
  4. The holdout: one visitor in five on a new site is held back on purpose. Test with several visitors, not one.
  5. A visitor who bought in the last 24 hours, or who is in checkout, hears nothing by design.

​
The wrong sentence showed

The sheet is the source of every sentence, so a wrong sentence is a wrong or stale fact: an old free shipping line, a code that expired, a size note on the wrong handle, a zone whose countries are wrong. Read the sheet back with GET /v1/sdk/{id}/facts and fix it there. If the sentence is right for the sheet and wrong for the visitor (the home zone’s line said to a visitor abroad), add the zone for their country; a visitor whose country matches no zone hears nothing about shipping.

​
Visitors are spoken to but nothing is credited

The store view shows shoppers_helped rising and orders_credited at zero.
  • Orders must reach NextIntent from your server with the visitor id on them, within seven days of the moment. Without an order feed nothing can be credited. See Commerce endpoints.
  • The shown acknowledgement: a card that was placed but never acknowledged does not count as spoken to. If you render your own card from the event, send the ack.
  • The visitor id on the order must be the SDK’s id, carried through your checkout (the cart beacon stamps it on the cart; your order feed passes it along).

​
The store view is all sample rows

sample: true with a needs list. The site has forwarded no orders yet. Everything in daily and Moments is real; the money block fills in with the first order.

​
An API call answers 404 or 403

  • 404 on a site id you can see in a page: the site belongs to another account, or the key is bound to a different site. A bound key cannot list sites.
  • 403 read_only: a viewer key making a write. Mint an admin key.
  • 403 insufficient_scope: the key’s scopes do not include the one the route needs; the answer names it.
  • 401: the key was revoked or expired, or the header is missing Bearer .
  • 429: over 600 requests a minute for the key; back off for the Retry-After seconds.