Hinto Signal

​

One app, every product

• Your sign-in provider. When customers sign in with Supabase, Firebase, Clerk, Auth0, or another OpenID provider, name that provider once in Hinto, and the app passes the provider’s own token. The app needs no backend and no backend values. See Use your sign-in provider’s token.
• Your backend. It signs a token with the backend values. See Issue a token on your authenticated server.

​

What Signal shows your customers

​

Set up with a coding agent

1. Answers your product questions, or says “defaults” (step 2).
2. Types your pairing code in Hinto and approves it (step 4).

​

1. Read the repository

• The Hinto API. Set HINTO_API_URL in your shell to https://api.gethinto.com. Use another Hinto API only if the prompt that sent you here names one. Do not take the API from Hinto URLs already in the repository or its env files, such as NEXT_PUBLIC_HINTO_INGEST_URL or a dev-api address. They come from older setups. Leave Hinto keys already in env files alone until step 4 tells you whether to replace them.
• Signal values already in use. Look in this repository’s env files, and in the backend that signs tokens for the organization’s website when you can read it, for NEXT_PUBLIC_HINTO_PUBLISHABLE_KEY, VITE_HINTO_PUBLISHABLE_KEY, EXPO_PUBLIC_HINTO_PUBLISHABLE_KEY, older *_HINTO_INGEST_KEY names, and HINTO_SIGNAL_APP_ID, HINTO_SIGNAL_KID, and HINTO_SIGNAL_SECRET. Step 4 tells you whether to reuse them.
• An existing chat. A component that renders a message list and a composer, an /api/chat route, or an import of ai, @ai-sdk/*, openai, @anthropic-ai/sdk, or langchain. Note the file where the chat lives.
• An existing support widget. A third-party script or package such as Intercom, Crisp, Zendesk, or HubSpot chat. It is not a chat you plug Hinto into. Note it for step 2.
• React version. With an existing chat in any framework, plug Hinto into it. With React 19 and no chat, install the full conversation. Otherwise install session capture only, as in Browser SDK.
• Development origins. Read the dev script and config for the port: next dev -p 3003 means http://localhost:3003. Next.js defaults to port 3000 and Vite to 5173.
• Production origin. Look in vercel.json, netlify.toml, fly.toml, a CNAME file, metadataBase, site URL variables, and the README.
• Sign-in. How the server reads the signed-in user, that user’s stable ID, and where sign-out happens. Also find where the server reads the user’s name and email, and their company, organization, or workspace name when the app has one.
• Sign-in provider. Whether customers sign in with Supabase, Firebase, Clerk, Auth0, or another OpenID provider, and the value Hinto needs from the app’s config for it, as Use your sign-in provider’s token lists: the Supabase project URL, the Firebase project ID, the Clerk Frontend API URL, or the Auth0 domain and API audience. Also note whether the app has a backend that can sign tokens. A React Native app on Supabase, or a single-page app on Firebase, often has none.
• The entry point. The signed-in UI where support fits: an account menu, a help menu, the header, or a sidebar. Note any existing Sheet or Dialog component.
• The critical journey. One signed-in flow with an explicit success and failure, such as connecting an integration, checkout, submitting onboarding, or inviting a teammate. Prefer an integration connection when the product has one. Find five places in its code: the entry point where the flow begins, the submit handler, the existing error branch, the point where the server confirms success, and the component that shows the failure to the customer. The help offer goes in that component.
• Deploy platform. A linked project (.vercel/project.json, .netlify/state.json, fly.toml) and whether its CLI is installed and signed in (vercel whoami, netlify status, fly auth whoami).

​

2. Agree on what customers will see

• Ask topics change what customers see in a way the person cares about. Ask them before you build, unless the code already answers them.
• Decide topics have a safe default. Do not ask. Use the default and list it under “Decisions I made” in step 10, so the person can change it later.

Before I start: I’ll add a Support item to your account menu that opens a side panel. When a customer gets stuck connecting Stripe, I’ll also show a small help card next to the Connect button, offering to try again or contact support. Say “defaults”, or tell me what to change.

​

3. Start pairing

curl -sS -X POST "$HINTO_API_URL/v1/signal/pair" \
  -H "Content-Type: application/json" \
  -d '{"client_name":"Claude Code","origins":["http://localhost:3000","https://app.example.com"]}'

​

4. Show the code, then poll until approved

Open https://app.gethinto.com/pair and type WDJB-MJHT to approve this app. I’ll keep going when you do.

curl -sS -X POST "$HINTO_API_URL/v1/signal/pair/token" \
  -H "Content-Type: application/json" \
  -d "{\"device_code\":\"$DEVICE_CODE\"}"

1. Write publishableKey as the publishable key in step 5. It is the same key the organization’s other products use.
2. Reuse the backend values the organization already has: HINTO_SIGNAL_APP_ID, HINTO_SIGNAL_KID, and HINTO_SIGNAL_SECRET. Look in this repository’s env files first, then in the env of the backend that already signs tokens for the organization’s website, when you can read it. Keep the three values together, as that backend uses them. HINTO_SIGNAL_APP_ID must equal applicationId.
3. If this app talks to that same backend, and the backend already has a token endpoint, use that endpoint in step 7. This app then needs no backend values of its own.
4. Skip step 6 for values production already has.

​

5. Write the local environment

​

6. Set the deploy variables

grep '^HINTO_SIGNAL_SECRET=' .env.local | cut -d= -f2- | tr -d '\n' | vercel env add HINTO_SIGNAL_SECRET production --sensitive

​

7. Install and wire the app

1. Install the exact release, and import one of its two stylesheets once, as that section says.
2. Give the conversation a token. On the sign-in provider path, use your sign-in provider’s token: copy that provider’s getToken function next to the runtime, and add no server route. Otherwise, issue a token on your authenticated server at /api/support-token. Include the signed-in user’s email, name, and company when the app has them. Read them from the server-side session, never from the request.
3. Create capture and conversation together, once per signed-in user. On the sign-in provider path, pass the provider’s getToken and the provider’s user ID as subject. The runtime sets the customer’s identity in capture. Do not add identify calls with an email or another kind of identity.
4. Place the conversation in your product at the entry point from step 2, with the uploads and status choices from step 2.
5. Instrument one journey, the critical journey from step 1, as Journeys describes. Add calls only to the flow’s existing handlers. Never add product behavior, server routes, or test hooks to make the flow fail. If the flow is a stub, or has no real point where it succeeds or fails, skip the journey and say so in the step 10 summary.
   • Call capture.journey(key) at the flow’s entry point. It is idempotent, so a re-render is safe.
   • Call attempt(action) in the submit handler, before the request.
   • Call fail({ action, category, feedback }) in the existing error branch. Map each error to one category: client_validation, prerequisite, permission, third_party, network, server, or unknown.
   • Call succeed() only after the server confirms, never on click.
   • When the submit control can be disabled, report attempt with feedback from a wrapper, because a disabled control emits no click.
   • Put only tokens in metadata, such as a plan or a provider. Never put user data there.
6. Place the help offer for that journey, unless the person said no in step 2, as Offer help on the journey describes. The journey alone shows the customer nothing. A stuck customer sees an offer only where a slot is placed. Put <Support.HelpOffer journey="..." topic="..." onRetry={...} /> in the component from step 1 that shows the failure, next to the control that fails, under the Support.Provider you mount in item 4. Use the same key as the journey, the step in the customer’s words as topic, and the step’s existing handler as onRetry. Keep it mounted, never inside a condition. It renders nothing until support has started for a signed-in customer. If you skipped the journey, skip the slot.

​

8. Check your work

1. Run the project’s typecheck and build.
2. Start the dev server in the background.
3. Request /api/support-token without a session. Expect 401. On the sign-in provider path there is no endpoint: skip checks 3 and 4, and check 6 proves the token. For Supabase, request https://<ref>.supabase.co/auth/v1/.well-known/jwks.json instead and expect at least one key. No keys means the project still signs with its legacy JWT secret, which Hinto does not accept.
4. Sign in the way the app allows in development, such as a seeded or demo account, and request /api/support-token with that session. Expect 200 with { "token": ... }. If signing in needs the person’s own password, skip this check and say so.
5. Ask Hinto which app the publishable key belongs to, from each development origin. Set HINTO_PUBLISHABLE_KEY in your shell from the publishable key in .env.local. Expect 200 with your applicationId. The browser makes this same request when support starts.

curl -sS "$HINTO_API_URL/v1/native-support/config" \
  -H "Authorization: Bearer $HINTO_PUBLISHABLE_KEY" \
  -H "Origin: http://localhost:3000"

6. If you can drive a browser, open the app, sign in, and open support. Confirm the conversation loads and the console shows no Hinto errors. A conversation that asks the customer to sign in again means Hinto refused the token: see Troubleshooting.
7. If you can drive a browser, run the journey once, the way a customer would, with debug: true passed to initHinto. Do not force a failure. The SDK writes its debug lines with console.warn and a [Hinto] prefix, so they are warnings, not errors. Each ingest response: accepted N, duplicates N, rejected N line covers one whole batch. In the Network tab, find the /v1/ingest request whose body contains the journey events. The check passes when the response line for that batch shows rejected 0. Remove debug: true afterwards. If you skipped the journey in step 7, skip this check.
8. If you can drive a browser, sign in, open the screen where the journey runs, and confirm it has an element with data-hinto-part="help-offer". Signed out, the slot renders nothing. The element is empty until Hinto offers help, so do not expect a card. Do not force a failure to bring one. If you placed the offer in your own chat, skip this check.
9. Run the project’s typecheck again.
10. Stop the dev server you started.

​

9. Stage the first ticket

npx @gethinto/signal@0.1.1 stage --reproduce 14 --message "Export fails after login: I click Export and nothing happens."

1. One of the imported tickets the prompt lists. Pass its number as --reproduce, do what the customer described, and write the same complaint in your own words.
2. A real defect you found while reading the code. Reproduce it the way a customer would.
3. A failure path under a blocked request: --block "POST /api/export" aborts that request in the browser, so the app’s own error handling runs. Hinto records it as simulated and says so on the ticket.
4. A walk through the key flow from step 1 that ends with a question about it.

​

10. Finish with a short summary

• What I added: one line naming the path you took (the Support panel, the existing chat, or session capture only), the files and the entry point, one line each, and one line naming the journey, where it reports, and where help is offered, for example “The Stripe connection journey reports from ConnectStripe.tsx, and a stuck customer is offered help next to the Connect button.” If you skipped the journey, say why in one line, for example “I added no journey, because the Stripe connection page is a placeholder with no real success or failure.” With the existing chat, the entry point is the file where the handoff lives.
• What your customers will see: one line per piece from What Signal shows your customers that you installed, saying where and when it appears. For example: “A Support item in the account menu opens a side panel. After a customer writes, they get an automatic reply and a status. When someone is stuck connecting Stripe, a help card appears next to the button.” Always add: “Signal records what signed-in customers do in your app, never what they type. Check that your privacy policy covers it.”
• Decisions I made: each Decide default from step 2 in one line, and each Ask answer you used a default for. Say where to change it, in plain words: in the code, or in Hinto under Settings > Auto-responses, or Settings > Hinto Signal for help offers. For how customers sign in, say which one you used, for example “Support trusts your Supabase sign-in, so I added no server code. An admin can change this under Sign-in provider in Settings > Hinto Signal.”
• What you need to do: “Nothing.” Or the one block of deploy commands from step 6. Or the one setting the sign-in provider needs, from Use your sign-in provider’s token, such as moving a Supabase project off its legacy JWT secret or shortening an Auth0 token lifetime.
• See it working: for example, “Run npm run dev, sign in, and choose Support in the account menu. Send a message. It appears in your Hinto Inbox, and your reply there appears in the app.”

​

The Hinto MCP server is optional

​

Set up without an agent

1. In Hinto, open Settings > Hinto Signal as an organization admin.
2. If the organization has no Signal app yet, choose Set up without a coding agent. Hinto shows the publishable key and the backend values. The signing secret is shown once: copy the backend block now.
3. Put the publishable key in each website’s and mobile app’s env, as NEXT_PUBLIC_HINTO_PUBLISHABLE_KEY, VITE_HINTO_PUBLISHABLE_KEY, or EXPO_PUBLIC_HINTO_PUBLISHABLE_KEY. It is public and safe to ship.
4. Choose how the app proves who the customer is:
   • If customers sign in with Supabase, Firebase, Clerk, Auth0, or another OpenID provider, under Sign-in provider choose Use a sign-in provider, pick the provider, enter the values Use your sign-in provider’s token lists, and choose Save. The app then passes that provider’s token, and needs no backend values.
   • Otherwise, put the backend block (HINTO_SIGNAL_APP_ID, HINTO_SIGNAL_KID, and HINTO_SIGNAL_SECRET) in your backend’s env. Never send the secret to a browser or a phone.
5. Under Products, choose Add website for each website, with its exact origin, such as https://app.example.com and http://localhost:3000. A mobile app needs nothing here.

​

Install the exact release

npm install @gethinto/browser-sdk@0.9.2 @gethinto/native-support-react@0.6.2

​

Use your sign-in provider’s token

• Supabase: url is the project URL the app’s Supabase client uses. The project must sign with JWT signing keys, the default for new projects. A project that still uses the legacy JWT secret signs with HS256, which Hinto does not accept from a provider. Its owner migrates it in the Supabase dashboard under JWT Keys (Migrate JWT secret, then Rotate keys), or the app signs tokens on a backend instead.
• Firebase: projectId is projectId in the app’s Firebase config.
• Clerk: url is the Frontend API URL from the Clerk dashboard, such as https://clerk.example.com in production or https://example.clerk.accounts.dev in development, with no path.
• Auth0: domain is the tenant domain, and audience is the identifier of the Auth0 API the app requests tokens for. A token requested without audience is not a JWT, and Hinto cannot read it. Auth0 issues API access tokens for 24 hours by default: set the API’s maximum token lifetime to 43200 seconds (12 hours) or less.
• Another OpenID provider: issuer is exactly the iss value in the app’s tokens. Hinto reads the keys from <issuer>/.well-known/openid-configuration, which must name the same issuer. audience is required.

• It is signed with RS256, RS384, RS512, PS256, ES256, ES384, or EdDSA, by a key the provider publishes. Hinto never accepts HS256 from a provider.
• iss is the provider’s issuer, and aud contains the audience (Supabase: authenticated; Firebase: the project ID; Auth0 and other providers: the audience you sent). Clerk tokens have no audience check.
• It has sub, iat, and exp, has not expired, and lives 12 hours or less.
• sub equals the subject the app passes to the SDK. Use the same ID for capture’s initialIdentity.

// Pass one of these as `getToken`. Hinto calls it with `true` after a 401: return a fresh token then.
// Each throws when nobody is signed in, which shows the conversation's sign-in state.

// Supabase (@supabase/supabase-js). subject: session.user.id
export const supabaseToken = (supabase) => async (forceRefresh) => {
  const { data } = forceRefresh
    ? await supabase.auth.refreshSession()
    : await supabase.auth.getSession();
  if (!data.session) throw new Error("Support authentication required");
  return data.session.access_token;
};

// Firebase (firebase/auth). subject: auth.currentUser.uid
export const firebaseToken = (auth) => async (forceRefresh) => {
  if (!auth.currentUser) throw new Error("Support authentication required");
  return auth.currentUser.getIdToken(forceRefresh);
};

// Clerk: `getToken` from useAuth() or Clerk.session. subject: userId
export const clerkToken = (getToken) => async (forceRefresh) => {
  const token = await getToken({ skipCache: forceRefresh });
  if (!token) throw new Error("Support authentication required");
  return token;
};

// Auth0 (@auth0/auth0-react or @auth0/auth0-spa-js). `audience` is the API identifier you gave
// Hinto. subject: user.sub
export const auth0Token = (getAccessTokenSilently, audience) => (forceRefresh) =>
  getAccessTokenSilently({
    authorizationParams: { audience },
    cacheMode: forceRefresh ? "off" : "on",
  });

​

Issue a token on your authenticated server

import { createHmac } from "node:crypto";

// `profile` comes from your server session or user record, never from the request.
export function signSupportToken(subject, appId, kid, secret, profile = {}) {
  if (!subject || !appId || !kid || !secret)
    throw new Error("Missing authenticated subject or signer configuration");
  const { email = null, name = null, company = null } = profile;
  const now = Math.floor(Date.now() / 1000);
  const encode = (value) => Buffer.from(JSON.stringify(value)).toString("base64url");
  const claims = { sub: subject, email, name, company, aud: appId, iat: now, exp: now + 3600 };
  const input = `${encode({ alg: "HS256", typ: "JWT", kid })}.${encode(claims)}`;
  return `${input}.${createHmac("sha256", secret).update(input).digest("base64url")}`;
}

​

Create capture and conversation together

import { initHinto } from "@gethinto/browser-sdk";
import { connectConversation } from "@gethinto/browser-sdk/conversation";
import { createSupportUI } from "@gethinto/native-support-react";

export async function startSupport(options: {
  customerId: string;
  publishableKey: string;
  apiUrl?: string;
  tokenUrl?: string;
}) {
  const getToken = async () => {
    const response = await fetch(options.tokenUrl ?? "/api/support-token", {
      credentials: "same-origin",
      cache: "no-store",
    });
    if (!response.ok) throw new Error("Support authentication required");
    const data = (await response.json()) as { token: string };
    return data.token;
  };
  const capture = initHinto({
    apiKey: options.publishableKey,
    apiUrl: options.apiUrl,
    initialIdentity: { kind: "external_id", value: options.customerId },
  });
  const client = await connectConversation({
    capture,
    ingestKey: options.publishableKey,
    apiUrl: options.apiUrl,
    auth: {
      subject: options.customerId,
      getToken,
    },
  }).catch((error: unknown) => {
    capture.shutdown();
    throw error;
  });
  const ui = createSupportUI(client);
  return {
    capture,
    ui,
    switchCustomer(subject: string | null) {
      client.updateAuth(
        subject
          ? {
              subject,
              getToken,
            }
          : null,
      );
    },
    destroy() {
      ui.destroy();
      client.destroy();
      capture.shutdown();
    },
  };
}

​

Place the conversation in your product

import { Support } from "@gethinto/native-support-react";

// The default composition: messages with the status row, and a composer with uploads.
export function ProductConversation() {
  return <Support.Conversation className="customer-support" />;
}

​

Verify the integration