# Voice Agents

> Create AI agents that handle phone calls, generate personalized outreach, and automate voice interactions.

Source: https://docs.graph8.com/ai-features/voice-agents/

Voice agents are AI personas that make and receive phone calls, generate personalized outreach copy, and respond to emails — all using your org's context and knowledge base. Each agent has a configurable personality, voice, phone number, and set of skills.

## How It Works

1. Go to **Agents → Agents**
2. Click **New** and choose **Agent** or **Twin**
3. Configure the agent's persona, identity, and knowledge
4. Attach skills and activate

## Agents vs. Twins

| Type | Purpose | Extra Features |
|------|---------|----------------|
| **Agent** | General-purpose AI persona for calls, emails, and chat | Preset voice selection |
| **Twin** | Digital replica of a real person | Custom voice cloning, LinkedIn profile extraction, writing style upload |

Twins inherit their source agent's persona, role, and voice — then layer on personal context from LinkedIn data and writing samples to match the real person's tone.

## Persona

The **Persona** tab controls how your agent communicates.

| Setting | What It Controls |
|---------|-----------------|
| **Role** | SDR, AE, Receptionist, CSM, GTM Engineer, Intake, or Custom |
| **Tone / Formality** | Casual (0.1) → Moderate (0.5) → Formal (0.8) |
| **Conciseness** | Detailed (0.1) → Balanced (0.5) → Direct (0.8) |
| **Assertiveness** | Gentle (0.1) → Balanced (0.5) → Assertive (0.8) |
| **Persona Prompt** | Full free-text instructions for the agent's behavior |
| **Outbound Call Instructions** | Override behavior specifically for outbound calls |
| **Inbound Call Instructions** | Override behavior specifically for inbound calls |
| **Voicemail Message** | Per-agent voicemail script (falls back to org-level if empty) |

Voicemail messages support template variables: `{first_name}`, `{bot_name}`, `{company_name}`.

## Identity

The **Identity** tab assigns communication channels to your agent.

- **Phone Number** — select from available Twilio numbers. Required to make or receive calls
- **Voice** — choose a preset Cartesia voice (Michael, Sarah, David, Emma, and others) or, for twins, clone a custom voice
- **Calendar** — link an appointment type for booking meetings during calls
- **Company Knowledge** — toggle access to the org-wide knowledge base

### Voice Cloning (Twins Only)

1. In the agent form, switch to **Custom** voice mode
2. Click **Clone New Voice**
3. Select a sample script (Professional, Conversational, or Friendly)
4. Record up to 10 seconds of audio or upload a WAV/MP3 file
5. Click **Clone Voice**

Cloned voices are saved to your org and can be reused across multiple twins.

## Knowledge

Agents can access two types of knowledge:

- **Company Knowledge** — org-wide context including company description, services, products, pain points, value proposition, pitch, FAQs, target audience, and competitive advantage
- **Collections** — up to 4 document collections per agent. Documents are chunked and vectorized for retrieval during conversations

## Skills

Attach reusable AI skills to give your agent capabilities beyond conversation. Go to the **Skills** tab on the agent detail page and click **Attach Skills**.

Skills have three runtime types:

| Type | What It Does |
|------|-------------|
| **LLM** | Runs a prompt template against an AI model with configurable temperature and token limits |
| **API** | Calls an external HTTP endpoint with method, headers, body template, and auth |
| **Script** | Executes Python, JavaScript, or TypeScript code with configurable timeout (up to 300s) |

Skills can require human approval before execution. Execution history — including input, output, duration, token count, and cost — is tracked on the agent's **Activity** tab.

## On-Demand Content Generation

Voice agents power personalized content generation at send time across channels:

| Channel | What Happens |
|---------|-------------|
| **Email** | Per-contact personalized email generated using CDP data, campaign context, and conversation history |
| **LinkedIn** | Per-contact LinkedIn message generated at send time — no static templates needed |
| **Call Script** | Per-contact call script generated with live CDP data before dialing |
| **Voicemail** | Dynamic voicemail message personalized per contact |

On-demand generation pulls from your Global Context, campaign documents, and the contact's enrichment data. Twin tone profiles (formality, conciseness, assertiveness) are applied to match the sender's style.

## Phone Calls

### Outbound Calls

Agents can place outbound calls via Twilio or Telnyx. Each call links to a campaign and sequence step for attribution. After the call, a callback delivers the transcript, summary, disposition, sentiment, recording, and duration.

### Inbound Calls

Assign a phone number to an agent to handle inbound calls automatically. The agent uses your inbound instructions, company knowledge, and attached collections to respond. If the agent can't resolve the call, it falls back to voicemail or queues for an SDR to claim.

## Outbound Playbooks

A playbook is a structured outbound script attached to an agent. Playbooks make calls consistent across prospects and let you A/B test scripts.

### Playbook Structure

| Section | Purpose |
|---------|---------|
| **Opening** | First 15 seconds — pattern interrupt, name drop, permission to continue |
| **Discovery** | 2–4 qualifying questions tied to ICP fit |
| **Value pitch** | Positioning aligned with the prospect's role and pain |
| **Objection handling** | Responses to the 5 most common objections |
| **Close** | CTA (book meeting, email resource, callback) and next-step confirmation |

### Attaching a Playbook

1. Open the agent's **Persona** tab
2. Paste the playbook into **Outbound Call Instructions**
3. Save — the agent reads the playbook top-to-bottom, branching on prospect responses

> **Tip:**
> Create one playbook per persona. A VP Sales playbook should sound different from a Marketing Director playbook — pain points, proof points, and CTAs all shift.

## Receptionist Routing Rules

Receptionist agents qualify and route inbound calls. Rules run in order — the first match wins.

### Rule Types

| Rule Type | When to Use |
|-----------|-------------|
| **Keyword match** | Caller mentions a word or phrase (e.g., "billing", "support", "demo") |
| **Intent classification** | Agent classifies caller intent (e.g., sales vs. support vs. existing customer) |
| **Business hours** | Route differently based on time of day and weekday |
| **Caller identity** | Route known contacts (from CRM) differently from unknown callers |
| **Voicemail fallback** | Default action when no other rule matches |

### Routing Actions

| Action | Behavior |
|--------|----------|
| **Transfer to human** | Warm or cold transfer to a phone number or user |
| **Transfer to another agent** | Hand off to a specialized AI agent |
| **Take a message** | Record a voicemail and email it to a recipient |
| **Book a meeting** | Pull up calendar and schedule on the call |
| **Hang up** | For known-bad numbers (sales lists, spam) |

### Warm vs. Cold Transfer

| Transfer Type | Behavior |
|---------------|----------|
| **Warm transfer** | Agent briefs the human before connecting — explains who's calling and why |
| **Cold transfer** | Agent connects the caller directly with no briefing |

Warm transfers take ~10 extra seconds but reduce friction for the human picking up.

## Post-Call Summary

After every call, graph8 generates a structured summary for CRM and coaching.

### Generated Fields

| Field | Description |
|-------|-------------|
| **Disposition** | Call outcome (Booked, Callback, Not Interested, etc.) |
| **Summary** | 2–3 sentence recap of what was discussed |
| **Key points** | Bulleted list of topics, objections, and commitments |
| **Next steps** | Action items for the rep (send case study, schedule follow-up) |
| **Sentiment** | Positive, Neutral, or Negative based on tone analysis |
| **Qualification score** | 0–100 based on discovery answers vs. ICP criteria |
| **Intent signals** | Buying signals surfaced during the call |

Summaries push to the connected CRM as activity notes and appear in the contact's Inbox timeline.

## Coaching Loop

Turn calls into training material without manual review.

### Auto-Flagged Calls

graph8 auto-flags calls that match coaching criteria:

- Calls with low qualification scores (missed discovery)
- Calls with unresolved objections
- Calls where transfer was triggered by frustration
- Calls with long silences or interruptions

Flagged calls appear in the agent's **Activity** tab with timestamps on the problem moments.

### Review Workflow

1. Open the **Activity** tab
2. Filter by flag type (e.g., "Missed Objections")
3. Click a call to open the transcript
4. Click any line to jump to that timestamp in the recording
5. Update the agent's call instructions based on what you learned

> **Tip:**
> Batch coaching weekly. Review 10 flagged calls, extract the 3 most common gaps, and update the playbook or objection-handling section. Redeploy and measure conversion delta.

## Webhook Events

Subscribe to voice events to build custom integrations.

| Event | When It Fires |
|-------|---------------|
| `call.started` | Agent picks up or dials out |
| `call.answered` | Far side answers |
| `call.ended` | Call completes (any disposition) |
| `call.transferred` | Call handed off to another party |
| `call.voicemail` | Agent leaves voicemail |
| `call.summary.generated` | Post-call summary is available |
| `agent.flagged` | Call auto-flagged for coaching |

Configure webhook URLs at **Settings → Developer → Webhooks**. Events are signed with HMAC-SHA256.

## Privacy and Recording Retention

| Setting | Default | Notes |
|---------|---------|-------|
| **Recording retention** | 90 days | Extend in **Settings → Compliance** |
| **Transcription retention** | Indefinite | Used for search, coaching, and analytics |
| **Two-party consent states** | Auto-notice | Agent plays a recording notice at call start in states requiring consent |
| **Do Not Call list** | Auto-scrubbed | Numbers on the DNC list are excluded from outbound campaigns |

> **Caution:**
> Check local call recording laws. graph8 enables the auto-notice by default, but you are responsible for compliance with state and country-level wiretap rules.

## Testing

Click **Test Digital Agent** on the agent detail page to run a test before going live.

### Phone Call Test

- **Outbound** — enter a phone number and click **Start Test Call**. A live status card shows call state (Dialing → Ringing → Active → Completed) with a real-time transcript
- **Inbound** — call the agent's assigned number from your phone. The modal shows the expected greeting and instructions

### Email Test

- **Respond** — select a pre-built scenario (Billing Inquiry, Technical Support, Sales Inquiry, Feature Request, Service Complaint), review the incoming email, and generate a response
- **Compose** — choose a scenario or write custom context, then generate a fresh email with recipient info and context

## Activity & Analytics

The **Activity** tab on the agent detail page shows a filterable feed of all interactions:

| Filter | What It Shows |
|--------|-------------|
| **Calls** | Inbound/outbound calls with transcript, audio player, summary, disposition, sentiment, and duration |
| **Skills** | Skill executions with status, token count, cost, input/output JSON, and errors |
| **Workflows** | Workflow runs with status, duration, input/output data |

The **Analytics** tab shows aggregate metrics: total calls, success rate, average duration, and total duration.

> **Tip:**
> Test both inbound and outbound calls before activating an agent. The real-time transcript in the test modal lets you verify persona behavior, knowledge retrieval, and call instructions without affecting live contacts.

## Next Steps

- [Skills →](https://docs.graph8.com/ai-features/skills/) — Create reusable AI actions for agents
- [Workflows →](https://docs.graph8.com/ai-features/workflows/) — Chain skills and actions into automated multi-step processes
- [Dialer →](https://docs.graph8.com/engage/dialer/) — Use agents with the parallel dialer for outbound calling
- [Sequencer →](https://docs.graph8.com/engage/sequencer/) — Enroll contacts in sequences that use agent-generated content