---
title: "Aid Voice"
description: "Our built-in voice agent. Answers and places calls with no server, knows who it is talking to, presses keypad keys, and records follow-ups."
canonical_url: "https://www.agent-identity.dev/docs/phone/aid-voice"
markdown_url: "https://www.agent-identity.dev/docs/phone/aid-voice.md"
last_updated: "2026-10-09"
x_farming_labs_generated_preamble: true
agent:
  tokenBudget: 1000
  task: "Run an agent's calls on Aid Voice and read what it did afterwards."
  outcome: "Calls are answered or placed by Aid Voice, and each ends with a call.ended event carrying the outcome, transcript and follow-ups."
  appliesTo:
    package:
      - "@aid/api"
      - "@agentidentity/sdk"
  prerequisites:
    - "The agent has a phone number."
  files:
    - "apps/api/src/hosted-agent.ts"
    - "apps/api/src/phone-sessions.ts"
  sideEffects:
    - "Calls run on Aid Voice count against the same call and minute limits as any other call."
  verification:
    - description: "Read the agent's Aid Voice settings."
      expect: "GET /v1/identities/{id}/hosted-agent returns instructions (null means the built-in default), greeting and voicemail settings."
  rollback:
    - "PUT the previous settings, or switch the incoming call action away from hosted_agent."
  failureModes:
    - symptom: "An Aid Voice call ends straight away with hangup_reason failed."
      resolution: "The server running the API has no AI key configured, so Aid Voice cannot start. Contact support."
    - symptom: "400: instructions must be at most 8000 characters."
      resolution: "Shorten the standing instructions."
---

# Aid Voice
URL: /docs/phone/aid-voice
LLM index: /llms.txt
Description: Our built-in voice agent. Answers and places calls with no server, knows who it is talking to, presses keypad keys, and records follow-ups.
Related: /docs/phone/placing-calls, /docs/phone/incoming-calls, /docs/phone/calls-and-events

<!-- farming-labs:agent-contract:start -->
## Agent Contract

Task: Run an agent's calls on Aid Voice and read what it did afterwards.
Outcome: Calls are answered or placed by Aid Voice, and each ends with a call.ended event carrying the outcome, transcript and follow-ups.

### Applies To

- Package: `@aid/api`, `@agentidentity/sdk`

### Prerequisites

- The agent has a phone number.

### Files

- `apps/api/src/hosted-agent.ts`
- `apps/api/src/phone-sessions.ts`

### Side Effects

- Calls run on Aid Voice count against the same call and minute limits as any other call.

### Verification

- Read the agent's Aid Voice settings.
  - Expected: GET /v1/identities/{id}/hosted-agent returns instructions (null means the built-in default), greeting and voicemail settings.

### Rollback

- PUT the previous settings, or switch the incoming call action away from hosted_agent.

### Failure Modes

- An Aid Voice call ends straight away with hangup_reason failed. — Recovery: The server running the API has no AI key configured, so Aid Voice cannot start. Contact support.
- 400: instructions must be at most 8000 characters. — Recovery: Shorten the standing instructions.
<!-- farming-labs:agent-contract:end -->

# Aid Voice

Aid Voice is our built-in voice agent. It answers an agent's calls, and places calls with a task, without a WebSocket
server or a webhook. New numbers use it for incoming calls by default.

- **Incoming:** set the incoming call action to `hosted_agent` (the default for new numbers).
- **Outgoing:** place a call with `mode: "hosted_agent"` and a `reason`. See [Placing calls](/docs/phone/placing-calls).

## Settings

All settings are optional. Until you save any, Aid Voice runs with built-in defaults.

```ts title="aid-voice.ts"
await org.phone.setHostedAgentConfig(agent.id, {
  instructions: "You answer for Blue Harbor Dental. Be warm and brief. Never quote prices; offer to email the price list.",
  greeting: "Thanks for calling Blue Harbor Dental, how can I help?",
  voicemailMode: "leave_message",
  voicemailGreeting: "Sorry we missed you. Please leave a message after the tone.",
});
```

```bash title="terminal"
curl -sS -X PUT "https://api.agent-identity.dev/v1/identities/$AID_AGENT/hosted-agent" \
  -H "authorization: Bearer $AID_KEY" -H 'content-type: application/json' \
  -d '{"instructions":"You answer for Blue Harbor Dental. Be warm and brief.","greeting":"Thanks for calling, how can I help?"}'
```

| Field | Meaning |
| --- | --- |
| `instructions` | Standing orders for every call, up to 8,000 characters. `null` uses the built-in default. |
| `greeting` | What it says when it answers an incoming call. Without one, it greets the caller in its own words. |
| `voicemail_mode`, `voicemail_greeting`, `voicemail_max_seconds` | What happens when a call would be declined. See [Incoming calls](/docs/phone/incoming-calls#voicemail). |

`GET /v1/identities/{id}/hosted-agent` reads them back. The voice is chosen on the incoming call action, from the voice
catalog: see [Incoming calls](/docs/phone/incoming-calls#the-voice).

## What it knows when a call starts

Every Aid Voice call starts with a briefing:

- **Itself:** the agent's name, handle and email address, and the number it is calling from or on.
- **Who it is talking to:** the other number, and if that number belongs to one of your [contacts](/docs/mail/contacts),
  their name, company and notes. Unknown callers are greeted neutrally.
- **The time**, in UTC.
- **The task**, on calls placed with a `reason`. If the task and the standing instructions conflict, the task wins.

## What it can do

| Tool | What it does |
| --- | --- |
| Press keys | Presses `0-9`, `*` and `#` to get through phone menus or enter an extension. Put known menu paths in the task or instructions. |
| End call | Hangs up after its last sentence has been spoken, once the conversation is over. |
| Add a follow-up | Records work for your agent to do after the call, with an action and details. |
| Update / withdraw a follow-up | Refines or cancels a follow-up it recorded earlier on the same call. |

It cannot run your own tools during the call. If your agent needs to act mid-call, use [Your agent](/docs/phone/your-agent)
instead. For anything that can wait, follow-ups cover it.

## Follow-ups

Open follow-ups are on the call as `follow_ups`, in order, and in the `call.ended` event as `followUps`:

```json title="follow_ups"
[
  { "id": "0193…", "seq": 1, "action": "Confirm Tuesday 9:30am cleaning", "details": "Front desk asked for a confirmation call Monday.", "status": "open" }
]
```

Withdrawn follow-ups are left out.

## Tool activity

`GET /v1/calls/{id}/tool-invocations` (`listToolInvocations`) lists what Aid Voice did, in order: the tool name, its
status (`started`, `succeeded`, `failed`), a short result, and when it started and finished. Calls run by your own agent
return an empty page.

```ts title="activity.ts"
const { items, hasMore } = await org.phone.listToolInvocations(call.id, { limit: 50 });
```

## Watching and stopping a call

Transcript lines are written while the call runs: read them with `GET /v1/calls/{id}/transcripts`.
`POST /v1/calls/{id}/hangup` ends any live call from outside, and you still get the `call.ended` event.

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.
Docs-scoped sitemap: [/docs/sitemap.md](/docs/sitemap.md).
Well-known sitemap: [/.well-known/sitemap.md](/.well-known/sitemap.md).