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

# Widget links

> Send someone a personal link to a conversation that already knows who they are — values they can't change, and the agent can speak first.

A **widget link** opens the website widget for one person, with [Initial Parameters](/conversation-flows/build/flow-settings#initial-parameters) you set when you create the link. Use it when:

* **You invite someone to a conversation** — a candidate to an interview, a customer to a follow-up. The agent greets them by name and knows why they're there.
* **The values must not be changed by the visitor.** A link's values are stored on our side; the page and the link itself contain only a random code. Nothing the visitor does can change them.

<Note>
  Values passed in the embed code or the page URL are part of the web page, so visitors can see and change them ([Pass details to the widget](/conversation-flows/channels/widget-parameters)). Values in a widget link are not. Use a widget link for anything that decides what someone is allowed to do.
</Note>

## Who speaks first

It depends on the agent's [execution mode](/conversation-flows/concepts/execution-modes):

| Mode | When the person opens the link |
| - | - |
| **Initiator** | The agent speaks first, using the link's values: *"Hi Jane, thanks for joining the interview for Senior Backend Engineer…"* |
| **Responder** | The widget opens and waits for the person to write, as on any page, but the agent already knows the link's values. |

An Initiator agent's widget only opens from widget links, so its widget channel has no **Install Widget** button. A page that embeds it without a link shows *"This assistant is only available through a personal link."*

## Create a link

### From the agent

1. Set the agent's execution mode to **Initiator** and add a **Widget** channel.
2. Click **Start Conversation** in the bottom toolbar and pick the widget channel.
3. Fill in the Initial Parameters. Optionally add a **Name** (the agent sees it) and **Your reference**: your own id for this person, such as a candidate id, returned in workflow events.
4. Pick **Link expires after**: 1, 7 (default), 30 or 90 days.
5. Click **Create link**. Copy the **link** to send it, or the **embed code** to show the conversation on your own page.

<Warning>
  Copy the link right away. For security it isn't shown again — if you lose it, create a new one.
</Warning>

### From a workflow

Add a [Conversation Flow](/nodes/communication/conversation-flow) node, pick the agent and its widget channel. Instead of a recipient, set the optional **Name**, **Your reference** and **Link expires after**; all three accept `{{ }}`. When the node runs it creates the link and passes it on to the step connected to its output — for example a **Send Email** step:

| Output | What it is |
| - | - |
| `url` | The link to send, for example in the email body: `{{conversation_flow.url}}` (use your node's key) |
| `embedHtml` | The embed code, if you show the conversation on your own page |
| `launchId` | The link's id |
| `expiresAt` | When the link stops working |

<Note>
  Like any step's output, the link is saved in the workflow's run history. Anyone who can view this workflow's runs can open it, so keep the expiry short when that matters.
</Note>

The node's **Conversation Started** branch runs when the person opens the link, and **Conversation Ended** when the conversation is stopped. Both carry the link's values as `initialParameters`. A typical recruiting workflow: a candidate applies → create a link → email it → when the conversation ends, score the interview.

### From your server (API)

When your own backend knows who the visitor is — it already sends interview invitations, or renders the order page — create links with the [Widget Launch API](/api/widget-launches). Create a **widget key** in **Settings → API access → Widget keys**, then `POST /v1/widget/launches` with the agent, its widget channel and the values. You get back the link and the embed code for that one person.

### From your AI assistant (MCP)

The `start_conversation` tool of the [MCP server](/mcp-server) creates a widget link when you pick a widget channel. It returns the link and the embed code.

## Open the link

* **The hosted link** opens a full-page chat — nothing to install.
* **The embed code** shows the same conversation inside your page. It looks like the regular widget snippet, with the link's code instead of the agent's ids.

One link is one conversation:

* The first open starts the conversation. Opening the link again — later, or on another device — continues the same conversation.
* Two people opening the link at the same moment land in the same conversation, not two.
* After the conversation ends, the link shows *"This conversation has ended."*
* After the expiry, a link nobody opened shows *"This link has expired."* A conversation that already started keeps working until it ends.

Anyone who has the link can read and continue the conversation, so send it only to the person it's for.

For the same reason, the hosted page removes the link's code from the address bar as soon as it opens. Reloading that page shows *"Open the link from your message again to continue."* — opening the link again continues the same conversation.

## Who can pass parameters

On a Responder agent, the widget channel's **Who can pass parameters** setting decides which values count:

| Setting | What the agent uses |
| - | - |
| **The page and widget links** (default) | Values from widget links, plus values from the embed code or page URL for anything the link didn't set. Link values always win. |
| **Only widget links** | Only values from widget links. Values on the page are ignored. |

Choose **Only widget links** when every value matters — for example, when an actor or instruction depends on the visitor's role.

## See where values came from

In [Conversations history](/conversation-flows/operate/conversations-history), the **Parameters** block marks values from a link as **Widget link**, and values the visitor could change as **Embed code** or **Page URL**.

## Next

<CardGroup cols={2}>
  <Card title="Pass details to the widget" icon="sliders" href="/conversation-flows/channels/widget-parameters">
    Values from the embed code or the page URL.
  </Card>

  <Card title="Start a conversation" icon="paper-plane" href="/conversation-flows/operate/start-conversation">
    The Start Conversation form for every channel.
  </Card>
</CardGroup>


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