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

# Embedded chat

> Put one of your custom agents in your own product as a chat widget, so your customers can ask about their delivery without contacting support.

A custom agent doesn't have to live in the Portal. Drop a snippet into your own web app — an order-status page, a tracking page, a help center — and your customers can ask one of your agents about their delivery, in your product, without a Nash account.

The embedded agent answers questions. It never acts.

## When to use this

* **"Where's my order?" arrives faster than your support team can answer it.** An agent on the tracking page handles the status question at the moment the customer has it.
* **Your tracking page already gets the traffic.** The customer is looking at the delivery; the chat sits next to it rather than in an email thread.
* **You want a specific agent, not a general one.** The widget talks to a custom agent you built — your instructions, your knowledge, your tone.

Don't use it for internal operations work. Your own team is better served by the Portal or [Slack](/nash-agent/channels), where an agent can actually change something. And don't reach for it when the customer needs an action taken — an embedded agent can't reschedule a delivery or start a refund.

## What it can and can't do

Embedded chat is read-only, always. That isn't a setting you can loosen: embedded conversations run on a read-only footing regardless of the agent's own execution mode, and every write action is blocked before it runs.

| It can                                             | It can't                                 |
| -------------------------------------------------- | ---------------------------------------- |
| Look up a delivery's status, ETA, and history      | Cancel, reschedule, or reassign anything |
| Answer from the agent's knowledge and instructions | Request a refund or start a return       |
| Summarize what's happening with an order           | Text or call a customer or driver        |
| Hand the customer an accurate next step            | Write anything back to your Nash data    |

<Note>
  An agent set to auto-execute in the Portal is still read-only when someone reaches it through the widget. Embedding an agent never widens what it can do.
</Note>

## How it works

Three pieces, and the one that matters is the third:

1. **A snippet on your page** registers a `<nash-agent>` element where you want the chat to appear.
2. **Nash serves the chat itself** in an iframe, so the widget's styling stays isolated from your page and yours from it.
3. **Your backend mints the token.** Each conversation needs a short-lived token, minted server-to-server with the agent's embed secret. The secret stays on your server and never reaches the browser.

That third piece is why there's no such thing as a public Nash agent: a visitor can only start a conversation your backend agreed to start.

## Set it up

<Steps>
  <Step title="Open the agent's Embed tab">
    Go to the custom agent in the Portal and open **Embed**, alongside Overview and Sessions.
  </Step>

  <Step title="List the domains allowed to load it">
    Add each host that may embed this agent. A wildcard covers subdomains — `*.example.com` — and an exact host covers just that one.
  </Step>

  <Step title="Generate the embed secret">
    Nash shows the secret once, at generation. Copy it into your backend's secret storage then; if you lose it, rotate it rather than hunting for it. Rotating invalidates the old secret immediately.
  </Step>

  <Step title="Add a token endpoint to your backend">
    Stand up an endpoint that exchanges the embed secret for a short-lived token, and have it decide who's allowed to chat and about which order. This is where your own authentication lives — a visitor who isn't signed in to your site shouldn't get a token.
  </Step>

  <Step title="Paste the snippet">
    Copy the install snippet from the Embed tab, point its token-endpoint attribute at the endpoint you just built, and drop it into your page. The preview beside the controls renders the same widget your customers will see.
  </Step>
</Steps>

## Scoping a conversation to one customer

Your token endpoint decides which order or delivery a conversation is about. Until it supplies that context, the widget starts nothing — it fails closed rather than opening a general-purpose chat on your customer-facing page.

<Warning>
  Treat that context as steering, not as isolation. It tells the agent which delivery the conversation is about; it isn't a per-row permission boundary between one customer and another. The firm boundary is that the agent is read-only and confined to your organization's data. Put the widget behind your own sign-in when the conversation would otherwise expose one customer's delivery to another.
</Warning>

Each visitor gets their own conversation. Sessions are keyed per visitor and per agent, so two customers on the same page never see each other's messages.

## What this version doesn't do

Worth knowing before you plan around it:

* **Chat only.** There's no call button in the widget; [voice](/nash-agent/channels) stays a Portal-side capability.
* **No history when a visitor comes back.** A returning customer starts a fresh conversation rather than picking up the earlier one.
* **No human handoff.** The widget doesn't route to a live agent — pair it with your existing support path for the questions it can't close out.

Each agent also has its own request limits, so a busy page can't run one agent away with you.

## FAQ

<AccordionGroup>
  <Accordion title="Can a visitor make the agent do something by asking the right way?">
    No. Read-only is enforced in two independent places — the credentials the embedded conversation runs under, and the confirmation gate that blocks every write action before it executes. Phrasing doesn't get around either one.
  </Accordion>

  <Accordion title="Does the embed secret ever reach the browser?">
    No. The browser only ever holds a short-lived token your backend minted. The secret stays server-side, and Nash shows it to you once, when you generate or rotate it.
  </Accordion>

  <Accordion title="What happens if someone copies my snippet onto their own site?">
    The domain allowlist you set on the Embed tab is checked when the widget starts a conversation, and their site would still need a token from your backend. Keep the allowlist tight and your token endpoint authenticated.
  </Accordion>

  <Accordion title="Which agents can be embedded?">
    Custom agents your organization owns. Nash-managed global agents can't be embedded, and configuring the Embed tab needs more than view-only access to the agent.
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={2}>
  <Card title="Custom agents" icon="robot" href="/nash-agent/custom-agents">
    Build the agent you want to embed — its instructions, scope, and knowledge.
  </Card>

  <Card title="Channels: Slack, SMS & voice" icon="phone" href="/nash-agent/channels">
    The other places Nash shows up, and the ways it reaches people for you.
  </Card>

  <Card title="Guardrails & confirmations" icon="shield-check" href="/nash-agent/guardrails">
    How Nash decides what runs automatically and what waits for approval.
  </Card>

  <Card title="Live-tracking embed" icon="map-location-dot" href="/reference/nash-embedding">
    Embed the tracking page the widget most often sits beside.
  </Card>
</CardGroup>