> ## 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.

# Agent links

> createAgentLink, listAgentLinks and deleteAgentLink: manage a private voice agent's links from your server.

```js theme={null}
import { createAgentLink, listAgentLinks, deleteAgentLink, TalkingAvatarApiError } from "@interviewflowai/talking-avatar/server";
```

A [private voice agent](https://docs.talking-avatar.dev/voice-agents/private-agents.md) takes calls only through its links. These functions make, list and delete them with your API key. They need Node.js 18 or later. The same operations are available over [REST](https://docs.talking-avatar.dev/api-reference/introduction.md).

## createAgentLink(options)

Makes a new link. **Returns** `Promise<AgentLink>`.

```js theme={null}
const link = await createAgentLink({
  apiKey: process.env.TALKING_AVATAR_API_KEY,
  agentId: "your-agent-id",
  name: "Interview with Jane",
  expiresAt: new Date(Date.now() + 7 * 86400_000),
  maxUses: 1,
});

sendEmail(candidate, link.url);
```

**apiKey** `string` *required*

Your `tav_…` API key.

**agentId** `string` *required*

The voice agent's ID: the last part of the editor's URL (`/voice-agents/<id>`). The **Share & embed** tab's examples include it.

**name** `string`

Who or what it's for, shown in the dashboard. Up to 120 characters.

**expiresAt** `Date | string` (default: in 24 hours)

When it stops working. At most a year away.

**maxUses** `number`

How many calls it may start, from 1 to 100,000 (1 for a one-time link). Default: any number until it expires.

**apiUrl** `string`

The API's base URL. Leave it out.

## listAgentLinks(options)

The agent's links, newest first, expired and used-up ones included (up to 200). **Returns** `Promise<AgentLink[]>`.

```js theme={null}
const links = await listAgentLinks({ apiKey, agentId });
const active = links.filter((l) => new Date(l.expiresAt) > new Date() && (l.maxUses == null || l.uses < l.maxUses));
```

Takes `apiKey`, `agentId` and the optional `apiUrl`.

## deleteAgentLink(options)

Deletes a link: it stops working right away. A call already on it carries on. **Returns** `Promise<void>`.

```js theme={null}
await deleteAgentLink({ apiKey, agentId, linkId: link.id });
```

Takes `apiKey`, `agentId`, `linkId` and the optional `apiUrl`.

## AgentLink

**id** `string`

The link's ID

**name** `string | null`

Who or what it's for

**url** `string`

The page to send: the agent's call page with the link's token. Add `&embed=1` to put it in an iframe.

**token** `string`

The link's secret, for the widget's `data-token`

**expiresAt** `string`

When it stops working (ISO 8601)

**maxUses** `number | null`

How many calls it may start; `null` for any number until it expires

**uses** `number`

How many calls it has started

**createdAt** `string`

When it was made (ISO 8601)

## TalkingAvatarApiError

Thrown when a request fails. Extends `Error`.

| Property | Description |
| - | - |
| `status` | The HTTP status: `400` invalid options, `401` invalid API key, `404` agent or link not found |
| `message` | What went wrong |

```js theme={null}
try {
  await createAgentLink({ apiKey, agentId });
} catch (error) {
  if (error instanceof TalkingAvatarApiError && error.status === 404) {
    // wrong agentId, or the agent belongs to another account
  }
}
```


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