> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gethinto.com/llms.txt
> Use this file to discover all available pages before exploring further.

# @gethinto/browser-sdk

Browser session capture for [Hinto](https://gethinto.com).

Hinto investigates support tickets by reading evidence. This SDK is where most of that evidence comes from: it records what your users actually did in your app (page views and navigation, privacy-safe clicks, console messages, network request outcomes, and JavaScript errors), so an investigation can cite a real session instead of guessing. It is framework-agnostic, has no runtime dependencies, and never records form values, request or response bodies, headers, or cookies.

## Install

```
npm i @gethinto/browser-sdk@0.9.2
```

Use whichever package manager your project already uses.

## Native Support conversations

Since `0.4.0`, the root import and IIFE stay focused on session capture. The old widget launcher and root widget methods are removed. For an in-product customer conversation, call `connectConversation` from `@gethinto/browser-sdk/conversation` with the same publishable key as `ingestKey`; it resolves your organization and Signal app from that key. Install `@gethinto/native-support-react@0.6.2` for styled React 19 components. Follow the [Hinto Signal guide](https://docs.gethinto.com/native-support.md). Existing widget tickets remain historical read-only records in Hinto.

Since `0.6.0`, a conversation carries `status`: the support phase (`received`, `investigating`, `with_team`, `replied`, or `resolved`) and the steps the customer sees, worded with your organization's copy. It is null when the server sends none or sends one this version does not understand. A message's `origin` is `"automatic"` for your team's automatic reply and null otherwise; `unreadCount()` does not count the automatic reply. The runtime polls at the server's `status.refreshAfterMs`, between 3 and 60 seconds, and every 15 seconds without a status. While the conversation is closed, a visible tab still refreshes `unreadCount()` about once a minute and when it returns to the foreground. A hidden tab keeps the last-known count.

Since `0.7.0`, `runtime.offers` holds the Hinto Signal help offer for the signed-in customer's journeys. It renders nothing. Subscribe, call `show(id)` and render your own offer only when it returns `"ok"`, then call `dismiss(id)`, or `contact(id, { message })` when the customer chooses Contact support. Call `await offers.refresh()` after `journey.succeed()` to drop the offer at once.

Since `0.8.0`, `contact` queues one message in the customer's words that names the offer, and the runtime sends it when the conversation is open: call `runtime.open()` after it. It joins the active conversation or starts one, and a second click while it is on its way answers `"unavailable"`. `accept` is removed. The React kit's `Support.HelpOffer` does all of this for you.

```js
const offers = conversation.offers;
offers.subscribe(async (snapshot) => {
  if (snapshot.status === "eligible" && (await offers.show(snapshot.offer.id)) === "ok")
    renderHelpCard(snapshot.offer);
  else if (snapshot.status === "shown")
    renderHelpCard(snapshot.offer); // after a reload
  else removeHelpCard();
});
helpCard.onContact = (offer) => {
  if (offers.contact(offer.id, { message: "I need help with connecting Stripe." }) === "started")
    void conversation.open();
};
```

## Use your own chat

Since `0.7.0`, a product that already has a chatbot keeps it. Pass `bot: { name }` to `connectConversation`, hand the conversation to your team with `send({ handoff: { reason, summary, transcript } })`, and mirror every message your bot shows the customer with `shareBotMessage({ id, text })` while the conversation is open. When it resolves, your bot answers again. Follow [Use your own chat](https://docs.gethinto.com/native-support-own-chat.md), which also covers bots that run only on a server.

## Set up

Initialize once at app startup, then link each signed-in user to their session with `identify`.

```js
import { initHinto } from "@gethinto/browser-sdk";

const hinto = initHinto({
  apiKey: import.meta.env.VITE_HINTO_PUBLISHABLE_KEY, // or NEXT_PUBLIC_HINTO_PUBLISHABLE_KEY
});

// After sign-in, link sessions to the customer so Hinto can cite them as evidence.
// Optional name/company/traits improve the customer record in the console (since 0.3.0):
hinto.identify({
  kind: "email",
  value: user.email,
  name: user.name,
  company: user.company,
  companyId: user.companyId,
  traits: { plan: user.plan },
});
```

The SDK sends to `https://api.gethinto.com` unless you pass `apiUrl` for a different Hinto deployment. Pass your publishable key (`hinto_pk_…`) as `apiKey`. It is in Hinto under Settings > Hinto Signal, and every website and mobile app of your organization uses the same one. It can only send session data and open support; it cannot read tickets, customers, or investigations. It ends up in your frontend bundle by design, but keep it in an environment variable so you can roll it without a code change. Add each website's exact origin under Products in Settings > Hinto Signal. Never put a secret key (`hinto_sk_…`) in a website.

## Why `identify` matters

Without `identify`, sessions still arrive, but nobody can tell whose they are. An investigation into "Priya cannot export her report" needs Priya's session, and `identify` is how Hinto finds it. Call it once the signed-in user is known, and again after a user switch. You can identify by email as above, or by your own user id with `{ kind: "external_id", value: user.id }`.

Native Support requires the `external_id` identity, with the same id the support token carries as `sub`: the id your server signs, or your sign-in provider's user id when the app passes the provider's token. The support widget reads the user's name, email, and company from that token, not from `identify`. See [Hinto Signal](https://docs.gethinto.com/native-support.md).

Optional fields (additive since 0.3.0): `name`, `company`, `companyId`, and `traits`. Older SDKs that send only `{ kind, value }` keep working. When `name` is omitted, the customer record uses the identifier itself (for example the email address), never a guessed local-part.

## API

`initHinto(config)` returns a client with:

* `identify(identity)`: attach the current session to a customer. `identify(null)` at sign-out starts a new anonymous session. With Native Support, the conversation runtime sets the identity; do not call `identify` with another kind of identity once it runs.
* `journey(key)`: report one flow. See [Journeys](https://docs.gethinto.com/journeys.md).
* `track(name, properties?)`: record a custom event.
* `flush()`: send any buffered events now.
* `shutdown()`: stop capture at once. Events not yet sent are dropped, including a send in progress, so `await hinto.flush()` first.

Every `initHinto` option is in [Install the browser SDK](https://docs.gethinto.com/browser-sdk.md#configuration).

## Privacy

The SDK records what your app did, not what your users typed. It never records
form values, request or response bodies, headers, or cookies. Network capture
stores the method, URL, status, and duration only.

Query strings are stripped from every captured URL by default. Every captured
URL (path segments included) and every payload string passes through redaction
patterns before it leaves the browser. The built-in patterns scrub email
addresses, bearer tokens, sensitive query parameters (`token`, `secret`,
`password`, API keys, OAuth `code`, and suffixed names like `reset_token`), and
long opaque strings such as hex ids and API tokens.

Two knobs let you tune this:

```js
initHinto({
  apiKey: import.meta.env.VITE_HINTO_PUBLISHABLE_KEY,
  // Keep named query parameters in captured URLs. Default keeps none.
  // The redaction patterns still run over whatever survives, so a parameter
  // named like a secret is scrubbed even when allowlisted. Allowlisting a
  // parameter is an explicit choice to capture its values.
  allowUrlSearchParams: ["page", "tab"],
  // Replace the default redaction patterns. This applies to URLs and payloads.
  // This replaces the built-in list rather than extending it, so include the
  // built-in shapes you still want (email, bearer tokens, sensitive params,
  // long opaque strings) alongside your own.
  redactPatterns: [/\/reset\/[A-Za-z0-9]+/g],
});
```

Since 0.2.0, `allowUrlSearchParams` takes an array of parameter names instead of
a boolean.

## Links

* Full install and troubleshooting guide: [https://docs.gethinto.com/browser-sdk](https://docs.gethinto.com/browser-sdk.md)
* Hinto: [https://gethinto.com](https://gethinto.com)

## License

MIT

## Classes

* [`ConversationConnectError`](https://docs.gethinto.com/sdk/conversation/classes/ConversationConnectError)
* [`ConversationRuntime`](https://docs.gethinto.com/sdk/conversation/classes/ConversationRuntime)

## Interfaces

* [`AttachmentAddResult`](https://docs.gethinto.com/sdk/conversation/interfaces/AttachmentAddResult)
* [`AttachmentRejection`](https://docs.gethinto.com/sdk/conversation/interfaces/AttachmentRejection)
* [`ConnectConversationOptions`](https://docs.gethinto.com/sdk/conversation/interfaces/ConnectConversationOptions)
* [`ContactSupportInput`](https://docs.gethinto.com/sdk/conversation/interfaces/ContactSupportInput)
* [`ConversationAttachment`](https://docs.gethinto.com/sdk/conversation/interfaces/ConversationAttachment)
* [`ConversationAuth`](https://docs.gethinto.com/sdk/conversation/interfaces/ConversationAuth)
* [`ConversationBot`](https://docs.gethinto.com/sdk/conversation/interfaces/ConversationBot)
* [`ConversationConfig`](https://docs.gethinto.com/sdk/conversation/interfaces/ConversationConfig)
* [`ConversationMessage`](https://docs.gethinto.com/sdk/conversation/interfaces/ConversationMessage)
* [`ConversationSendOptions`](https://docs.gethinto.com/sdk/conversation/interfaces/ConversationSendOptions)
* [`Handoff`](https://docs.gethinto.com/sdk/conversation/interfaces/Handoff)
* [`HandoffPayload`](https://docs.gethinto.com/sdk/conversation/interfaces/HandoffPayload)
* [`HandoffPayloadTurn`](https://docs.gethinto.com/sdk/conversation/interfaces/HandoffPayloadTurn)
* [`HandoffTurn`](https://docs.gethinto.com/sdk/conversation/interfaces/HandoffTurn)
* [`MutationResponse`](https://docs.gethinto.com/sdk/conversation/interfaces/MutationResponse)
* [`PendingCommand`](https://docs.gethinto.com/sdk/conversation/interfaces/PendingCommand)
* [`PendingSend`](https://docs.gethinto.com/sdk/conversation/interfaces/PendingSend)
* [`SupportConversation`](https://docs.gethinto.com/sdk/conversation/interfaces/SupportConversation)
* [`SupportOffer`](https://docs.gethinto.com/sdk/conversation/interfaces/SupportOffer)
* [`SupportOfferStore`](https://docs.gethinto.com/sdk/conversation/interfaces/SupportOfferStore)
* [`SupportStatus`](https://docs.gethinto.com/sdk/conversation/interfaces/SupportStatus)
* [`SupportStatusStep`](https://docs.gethinto.com/sdk/conversation/interfaces/SupportStatusStep)
* [`UploadedAttachment`](https://docs.gethinto.com/sdk/conversation/interfaces/UploadedAttachment)
* [`HintoClient`](https://docs.gethinto.com/sdk/index/interfaces/HintoClient)
* [`HintoConfig`](https://docs.gethinto.com/sdk/index/interfaces/HintoConfig)
* [`IngestBatchResponse`](https://docs.gethinto.com/sdk/index/interfaces/IngestBatchResponse)
* [`JourneyAttemptOptions`](https://docs.gethinto.com/sdk/index/interfaces/JourneyAttemptOptions)
* [`JourneyEventBase`](https://docs.gethinto.com/sdk/index/interfaces/JourneyEventBase)
* [`JourneyFailOptions`](https://docs.gethinto.com/sdk/index/interfaces/JourneyFailOptions)
* [`JourneyHandle`](https://docs.gethinto.com/sdk/index/interfaces/JourneyHandle)
* [`JourneyRef`](https://docs.gethinto.com/sdk/index/interfaces/JourneyRef)
* [`JourneyStartOptions`](https://docs.gethinto.com/sdk/index/interfaces/JourneyStartOptions)
* [`JourneySucceedOptions`](https://docs.gethinto.com/sdk/index/interfaces/JourneySucceedOptions)
* [`SessionIdentity`](https://docs.gethinto.com/sdk/index/interfaces/SessionIdentity)

## Functions

* [`attachmentTypeFor`](https://docs.gethinto.com/sdk/conversation/functions/attachmentTypeFor)
* [`connectConversation`](https://docs.gethinto.com/sdk/conversation/functions/connectConversation)
* [`createConversation`](https://docs.gethinto.com/sdk/conversation/functions/createConversation)
* [`isSupportReply`](https://docs.gethinto.com/sdk/conversation/functions/isSupportReply)
* [`initHinto`](https://docs.gethinto.com/sdk/index/functions/initHinto)

## Type Aliases

* [`AttachmentRejectionReason`](https://docs.gethinto.com/sdk/conversation/types/AttachmentRejectionReason)
* [`AttachmentType`](https://docs.gethinto.com/sdk/conversation/types/AttachmentType)
* [`BotMessageOutcome`](https://docs.gethinto.com/sdk/conversation/types/BotMessageOutcome)
* [`ConversationComposer`](https://docs.gethinto.com/sdk/conversation/types/ConversationComposer)
* [`ConversationConnectErrorCode`](https://docs.gethinto.com/sdk/conversation/types/ConversationConnectErrorCode)
* [`ConversationOutcome`](https://docs.gethinto.com/sdk/conversation/types/ConversationOutcome)
* [`ConversationSnapshot`](https://docs.gethinto.com/sdk/conversation/types/ConversationSnapshot)
* [`CurrentConversation`](https://docs.gethinto.com/sdk/conversation/types/CurrentConversation)
* [`DraftAttachment`](https://docs.gethinto.com/sdk/conversation/types/DraftAttachment)
* [`DraftAttachmentFields`](https://docs.gethinto.com/sdk/conversation/types/DraftAttachmentFields)
* [`DraftAttachmentProblem`](https://docs.gethinto.com/sdk/conversation/types/DraftAttachmentProblem)
* [`HandoffTurnAuthor`](https://docs.gethinto.com/sdk/conversation/types/HandoffTurnAuthor)
* [`NativeSupportErrorCode`](https://docs.gethinto.com/sdk/conversation/types/NativeSupportErrorCode)
* [`NativeSupportState`](https://docs.gethinto.com/sdk/conversation/types/NativeSupportState)
* [`SupportContactOutcome`](https://docs.gethinto.com/sdk/conversation/types/SupportContactOutcome)
* [`SupportOfferOutcome`](https://docs.gethinto.com/sdk/conversation/types/SupportOfferOutcome)
* [`SupportOfferSnapshot`](https://docs.gethinto.com/sdk/conversation/types/SupportOfferSnapshot)
* [`SupportStatusPhase`](https://docs.gethinto.com/sdk/conversation/types/SupportStatusPhase)
* [`SupportStatusStepState`](https://docs.gethinto.com/sdk/conversation/types/SupportStatusStepState)
* [`ConsoleLevel`](https://docs.gethinto.com/sdk/index/types/ConsoleLevel)
* [`JourneyEventPayload`](https://docs.gethinto.com/sdk/index/types/JourneyEventPayload)
* [`JourneyFailureCategory`](https://docs.gethinto.com/sdk/index/types/JourneyFailureCategory)
* [`JourneyFeedback`](https://docs.gethinto.com/sdk/index/types/JourneyFeedback)
* [`JourneyMetadata`](https://docs.gethinto.com/sdk/index/types/JourneyMetadata)

## Variables

* [`ATTACHMENT_TYPES`](https://docs.gethinto.com/sdk/conversation/variables/ATTACHMENT_TYPES)
* [`CONTACT_QUEUE_TTL_MS`](https://docs.gethinto.com/sdk/conversation/variables/CONTACT_QUEUE_TTL_MS)
* [`MAX_ATTACHMENT_BYTES`](https://docs.gethinto.com/sdk/conversation/variables/MAX_ATTACHMENT_BYTES)
* [`MAX_ATTACHMENTS_PER_MESSAGE`](https://docs.gethinto.com/sdk/conversation/variables/MAX_ATTACHMENTS_PER_MESSAGE)
* [`MAX_HANDOFF_TURN_LENGTH`](https://docs.gethinto.com/sdk/conversation/variables/MAX_HANDOFF_TURN_LENGTH)
* [`MAX_HANDOFF_TURNS`](https://docs.gethinto.com/sdk/conversation/variables/MAX_HANDOFF_TURNS)
* [`MAX_MESSAGE_LENGTH`](https://docs.gethinto.com/sdk/conversation/variables/MAX_MESSAGE_LENGTH)
* [`SUPPORT_STATUS_PHASES`](https://docs.gethinto.com/sdk/conversation/variables/SUPPORT_STATUS_PHASES)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.