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

# AI Voice Agent

> Let AI answer your phone, qualify callers, and book meetings

The AI Voice Agent is a conversational AI that answers your phone. It greets the caller, understands what they need, captures details, books appointments, and transfers to a human when appropriate. Available 24/7 and never sounds rushed.

Configure the AI agent in `/dashboard/communications/` under the **AI Agent** tab.

## What it can do

<CardGroup cols={2}>
  <Card title="Answer and greet" icon="phone-volume">
    Pick up calls and deliver your custom greeting in a natural voice.
  </Card>

  <Card title="Conversational handling" icon="comments">
    Multi-turn dialogue — handles "Hi, I have a question about pricing" without forcing a menu.
  </Card>

  <Card title="Intent routing" icon="signpost">
    Identifies sales / support / billing / general intents and routes accordingly.
  </Card>

  <Card title="Capture caller details" icon="address-card">
    Name, company, email, reason for calling — all logged to your CRM.
  </Card>

  <Card title="Book meetings" icon="calendar-check">
    Connects to [Calendar](/calendar/overview) — books a slot during the call.
  </Card>

  <Card title="Transfer to human" icon="arrow-right-arrow-left">
    Hands off to a ring group, queue, or specific extension when needed.
  </Card>

  <Card title="Voicemail intelligence" icon="voicemail">
    If you go to voicemail, the agent reads the caller's intent, summarizes, and tags urgency.
  </Card>

  <Card title="Multi-language" icon="language">
    Configurable per language — English, Spanish, French, German, and more.
  </Card>
</CardGroup>

## How it differs from an IVR

| IVR                     | AI Voice Agent                             |
| ----------------------- | ------------------------------------------ |
| Press 1 for sales       | "Hi, can I ask what you're calling about?" |
| Static menus            | Dynamic conversation                       |
| Caller adapts to system | System adapts to caller                    |
| Limited to digit input  | Free-form speech                           |
| Bad after 5+ options    | Handles open-ended needs                   |

You can use both: the AI agent on your main number, with an IVR fallback after-hours; or an IVR up front with the AI agent as one of the menu options.

## Set up the AI agent

<Steps>
  <Step title="Pick a voice persona">
    Multiple voice options — male/female, US/UK/AU accents, neutral or warm tone. Preview each one before picking.
  </Step>

  <Step title="Write the greeting">
    Short and friendly. "Hi, thanks for calling Acme. How can I help you today?"
  </Step>

  <Step title="Define intents">
    The categories of caller need you want to recognize and handle differently. Sales, support, billing, partnerships, careers — whatever your business has.
  </Step>

  <Step title="Map intent → action">
    For each intent, pick what the agent does — book a meeting, capture details and email a rep, transfer to a ring group, or handle inline with a knowledge-base lookup.
  </Step>

  <Step title="Set escalation rules">
    When does the agent transfer to a human? "After 3 failed attempts to capture email", "If the caller says 'manager'", "If the caller is upset". Hiveku ships sensible defaults.
  </Step>

  <Step title="Point a DID at the agent">
    From the **Numbers** tab, route a DID to the AI agent.
  </Step>

  <Step title="Test from your own phone">
    Call in, run through your common scenarios, refine the prompts.
  </Step>
</Steps>

## Voice personas

Each persona is a combination of TTS voice + speaking style. Hiveku previews all options inline so you can hear them before choosing.

<Info>
  Pick a voice that matches your brand. Casual D2C might pair well with a warmer, friendlier voice; B2B enterprise often calls for measured and professional. Don't over-think it — most customers don't notice the specific voice, but they do notice if it sounds robotic.
</Info>

## Knowledge base

Upload your FAQ, pricing page, product specs, support docs, or paste in URLs. The agent can answer factual questions inline without transferring.

```
Q: "What are your hours?"
→ Agent answers from KB: "We're open Monday through Friday, 9 to 6 Eastern."

Q: "How much does the Pro plan cost?"
→ Agent answers from KB: "The Pro plan is $79 per month, billed annually."
```

The KB is read during conversation; the agent cites the source page in the call transcript so you can audit accuracy.

## Booking a meeting on the call

If the caller wants a demo or consultation, the agent can offer slots from your [Calendar](/calendar/overview) and book directly:

```
Agent: "I can grab time on Sarah's calendar for a demo. Would tomorrow at 2 PM Eastern work?"
Caller: "Yes."
Agent: "Great. What's the best email to send the calendar invite to?"
Caller: "alex@example.com"
Agent: "Booked. You'll get a confirmation in a moment. Anything else?"
```

The booking lands on the right host's calendar with all the right details, including the call transcript attached as context.

## Transfer to human

The agent transfers when:

* The caller asks ("Can I talk to a person?")
* The caller is detected as upset or frustrated
* The agent fails to make progress on the intent (e.g., 3 reprompts on email)
* The caller's intent doesn't match any configured handler
* A configured "always transfer" intent is detected (e.g., "billing dispute")

Transfers can route to a ring group, a queue, or a specific extension. The destination agent gets a brief summary of the AI conversation so far so they don't start from zero.

## Transcripts and review

Every call with the AI agent is transcribed and stored on the call record under `/dashboard/communications/calls/`. You can:

* Listen to the audio
* Read the full transcript
* See the detected intent and confidence
* See which knowledge base entries were referenced
* Mark the call as "good" or "bad" — Hiveku uses these labels to flag patterns to refine

<Tip>
  Spend 30 minutes a week reviewing flagged calls in the first month after launch. The biggest improvements come from spotting cases where the agent gave a vague answer or escalated when it shouldn't have.
</Tip>

## Cost

The AI agent uses LLM tokens (for understanding and response) and TTS/STT (for speech). Usage shows up in your billing dashboard. A typical 3-minute conversation costs roughly the same as a few sales emails. See [Monitor Usage](/how-tos/monitor-usage).

## API

```bash theme={null}
# Update agent configuration
curl -X PATCH https://api.hiveku.com/api/communications/ai-agent \
  -H "Authorization: Bearer hk_live_xxx" \
  -d '{
    "greeting": "Hi, thanks for calling Acme. How can I help?",
    "voice_persona": "warm-female-us",
    "knowledge_base_ids": ["kb_pricing", "kb_faq"],
    "transfer_destination": "ring_group:sales"
  }'

# List recent AI agent calls
curl "https://api.hiveku.com/api/communications/calls?handled_by=ai_agent&limit=50" \
  -H "Authorization: Bearer hk_live_xxx"
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="The agent sounds robotic">
    Try a different voice persona — there's a wide quality range. Also keep prompts short; long agent responses sound more synthetic.
  </Accordion>

  <Accordion title="Callers can't get through to a human">
    Make sure the escalation rules include "if caller asks for a person" and that the transfer destination is configured. Test the escape hatch yourself.
  </Accordion>

  <Accordion title="The agent answers a question wrong">
    Check the call transcript for the cited KB source. If the source was wrong, update the KB. If the source was right but the agent paraphrased badly, add a more direct phrasing to the KB entry.
  </Accordion>

  <Accordion title="Calls get cut off mid-sentence">
    The agent uses voice-activity detection — if there's significant background noise on the caller's end, it may interrupt prematurely. Adjust the noise sensitivity in advanced settings.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Set up the AI receptionist" icon="rocket" href="/how-tos/setup-ai-receptionist">
    End-to-end walkthrough.
  </Card>

  <Card title="Sales AI Co-pilot" icon="wand-magic-sparkles" href="/sales/overview">
    The text-side counterpart that drafts emails and surfaces follow-ups.
  </Card>
</CardGroup>