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

# Private agents

> Only people with one of the agent's expiring links can call it.

A private agent takes calls only through its **links**. Each link works until it expires, or until it has started a set number of calls. Make one per person or visitor: a candidate's interview, a customer's onboarding call, a signed-in user's session.

## Make an agent private

1. Open the agent's **Share & embed** tab.
2. Under **Who can call**, choose **Private**.
3. Click **Save changes**.

Its public share link and public embeds stop working. You can still make **test calls** from the dashboard without a link.

## Create links in the dashboard

Under **Private links**:

| Field | Description |
| - | - |
| **For** (optional) | Who or what it's for, such as *Interview with Jane*. Up to 120 characters. |
| **Expires after** | 1 hour, 24 hours (default), 7 days, 30 days, or **Custom…** for a date and time (up to a year away) |
| **Max calls** (optional) | How many calls the link can start, from 1 to 100,000. Leave empty for any number. Use **1** for a one-time link. |

Click **Create link**, then **Copy link** next to it. The list shows each link's calls used, its expiry, and when it was made. Expired and used-up links are dimmed.

To stop a link right away, click its trash icon, then **Delete link**. A call already in progress on it carries on.

## Create links from your server

Make a link per user with your [API key](https://docs.talking-avatar.dev/dashboard/api-keys.md), for example when they sign in to your app.

```js SDK (Node.js 18+) theme={null}
import { createAgentLink } from "@interviewflowai/talking-avatar/server";

const link = await createAgentLink({
  apiKey: process.env.TALKING_AVATAR_API_KEY,
  agentId: "your-agent-id",                         // dashboard → Voice agents
  name: "Interview with Jane",                      // optional, shown in the dashboard
  expiresAt: new Date(Date.now() + 7 * 86400_000),  // default: in 24 hours
  maxUses: 1,                                       // default: any number of calls
});
// link.url: send it, or put it in your page
```

```bash cURL theme={null}
curl -X POST https://backend.talking-avatar.dev/api/talking-avatar/voice-agents/AGENT_ID/links \
  -H "Authorization: Bearer $TALKING_AVATAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Interview with Jane", "expiresAt": "2026-11-02T09:00:00Z", "maxUses": 1}'
```

The response includes the link's `url` (the agent's call page with the link's token) and its `token`. See [Create a link](https://docs.talking-avatar.dev/api-reference/agent-links/create.md), [`createAgentLink`](https://docs.talking-avatar.dev/sdk/agent-links), and the matching list and delete calls.

## Use a link

Send the link's `url` by email or chat:

```text theme={null}
https://app.talking-avatar.dev/agent/AGENT_ID?token=LINK_TOKEN
```

### Embed a private agent

```html Iframe theme={null}
<iframe src="LINK_URL&embed=1" allow="microphone; autoplay" style="width:100%;height:640px;border:0;border-radius:16px"></iframe>
```

```html Widget theme={null}
<script src="https://app.talking-avatar.dev/embed.js" data-agent="AGENT_ID" data-token="LINK_TOKEN" async></script>
```

Make the link on your server when you render the page, then put its `url` (plus `&embed=1`) in the iframe, or its `token` in the widget's `data-token`.

## What callers see

| Situation | Message on the call page |
| - | - |
| No token, or a wrong one | *This agent isn't available.* |
| The link has expired | *This link has expired.* |
| The link has started its maximum number of calls | *This link has no calls left.* |
| The agent is turned off | *This agent isn't available.* |

Each call started on a link counts as one use, at the moment the call starts. Calls on links are billed to your balance like the agent's other calls.


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