Which key goes where
Keys that start with
hinto_live_ or hinto_test_ come from older setups. They still work, and you do not need to replace them. See One app, every product.
No sessions arriving
Almost always an origin mismatch. Open your browser’s network tab and look for a failed request to/v1/ingest. A CORS error means the origin your app is served from is not on the websites list. Add it in Settings > Hinto Signal under Products with Add website, or have your coding agent pair again with that origin, which adds it to the list. Remember that http://localhost:3000 and http://127.0.0.1:3000 are different origins, as are different ports. A mobile app needs no entry.
Sessions arriving but not attached to anyone
identify is missing, or it runs before your user object is loaded. Call it after sign-in completes, and again after a user switch. See Identify users.
A 401 from the ingest endpoint
The key is wrong or was revoked, or an old key you rolled passed its 7 days. Copy the current publishable key from Settings > Hinto Signal.A 403 from the ingest endpoint
The app sends a secret key, or an older key made for another use. Use the publishable key from Settings > Hinto Signal. A secret key from Settings > API keys never works in a website or an app.Pairing fails
too_many_origins means the websites list would pass 10. An admin removes websites the organization no longer uses in Settings > Hinto Signal, then the agent polls again.
invalid_identity_provider means a value in identity_provider is not one Hinto can use. Its error_description says what to send. See Use your sign-in provider’s token.
identity_provider_conflict means the organization’s Signal app already trusts a different sign-in provider. An admin changes it under Sign-in provider in Settings > Hinto Signal, then the agent polls again.
multiple_applications means the organization still has more than one Signal app, from before Hinto allowed only one. Settings > Hinto Signal lists the extra apps at the top. An admin chooses Pause on each one, then the agent polls again.
Sessions arrive minutes late
When Hinto cannot be reached, the SDK keeps up to 500 events and retries after 5 seconds, doubling the wait up to 5 minutes. Look for failed/v1/ingest requests in the network tab, then fix the cause above.
Support messages fail to send
If the conversation shows an error right after anidentify call, the app replaced the customer’s identity. With Hinto Signal support, the conversation runtime sets the identity, so remove identify calls that pass an email or another kind of identity. See Identify users.
Support asks a signed-in customer to sign in again
The conversation shows its sign-in state when the support token is refused. In the network tab, a conversation request (its path ends in/conversation or contains /conversations) answering 401 means Hinto refused the token. No conversation request at all means the SDK refused the token first, with auth_invalid.
auth_invalid, before any request. The token’ssubis not thesubjectthe app passed, or the token is not a JWT. Pass the provider’s user ID assubject: Supabasesession.user.id, Firebaseuser.uid, ClerkuserId, Auth0user.sub. An Auth0 access token requested withoutaudienceis not a JWT: request it with the API identifier you entered in Hinto. A token your backend signs must also name the Signal app ID asaud.401from Hinto, with a token your backend signs. Checkkid,aud, and the secret against the backend values in Settings > Hinto Signal, and that the token lives 12 hours or less. After Roll secret, the old secret stops working after 12 hours.401from Hinto, with your sign-in provider’s token. Check, in order:- Settings > Hinto Signal names that provider under Sign-in provider, with the right value. A token from a provider Hinto was not told about is refused.
- The token’s header has an asymmetric
alg, such asRS256orES256. A Supabase project on the legacy JWT secret signsHS256, which Hinto never accepts from a provider. Migrate the project to JWT signing keys in the Supabase dashboard under JWT Keys, or sign tokens on a backend. - The token’s
issequals the issuer Hinto expects, and itsaudcontains the audience:authenticatedfor Supabase, the project ID for Firebase, the API identifier for Auth0, the audience you entered for another OpenID provider. expminusiatis 12 hours or less. Auth0 issues API access tokens for 24 hours by default: lower the API’s maximum token lifetime to 43200 seconds.
atob on its first two parts. Never paste a customer’s token into an online decoder.
A stuck customer never sees a help offer
Check these in order:- The journey reports: run it with
debug: trueand look forrejected 0. See Journeys. - A
Support.HelpOfferslot with the journey’s key is on the screen where the customer fails. Sign in first: the slot renders nothing until support has started for a signed-in customer, and then the page has an element withdata-hinto-part="help-offer". - Proactive help is on for the journey in Settings > Hinto Signal, and the customer has not reached an Offer limit: a recent offer, a recent Not now, or the weekly cap.