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

# Build a Voice Agent

> Step-by-step walkthrough for creating a voice-only agent. Inbound, outbound, or bidirectional calls via Twilio, Telnyx, SIP Trunk, or WhatsApp Calls. The wizard has 6 steps in this order: Voice Agent Settings, Appearance, Knowledge Base, Tickets & Leads, Integrations & Tools, Deployment.

<Note>
  Voice agents handle **phone calls only**. No chat. To enter, click **Create Agent** on the dashboard topbar, then **Voice Agent** in the picker. The wizard opens at **Step 1: Voice Agent Settings**.
</Note>

## Pre-flight

Before you start, have these ready:

* A **name** for your agent.
* A **brief description** of the call's purpose.
* A **telephony provider account** with at least one provisioned number (Twilio, Telnyx, SIP Trunk, or WhatsApp Calls). You'll plug it in at Step 6.
* Any **knowledge sources** (files, FAQs, URLs) for the agent to reference during calls.

The wizard runs at `/{lang}/create/voice/{step}`. The first step is `voice-settings`.

## Step-by-step

<Steps>
  <Step title="Step 1: Voice Agent Settings">
    Pick a voice from the **Voice Picker** (50+ Wittify voices, search and filter), set the **language**, write the **Core Instructions** (voice prompt), tune **Speaking Speed**, **Voice Temperature**, and 7 advanced fields (Min Silence Duration, End Call on Silence, Max Call Duration, Min Speech Duration, Widget Popup Delay, Ask for Feedback toggle), and pick a **Background Sound** (5 ambient options with volume).

    The **Agent Name** field lives here (voice-only skips Text Agent Settings entirely, so the name moves into this step).

    **Required to advance**: agent name, Core Instructions (max 2,500 characters).

    [Full step reference →](/en/Systems/AI-Agents/Wizard/Voice-Settings)
  </Step>

  <Step title="Step 2: Appearance">
    Brand the voice widget: colors, logo, avatar, launcher icon, position, voice screen text per language, post-call ratings, font.

    Voice variants don't have Chat Screen Text fields. The voice screen replaces them: greeting, connecting message, in-call placeholder, end-call message, plus voice-specific labels.

    [Full step reference →](/en/Systems/AI-Agents/Wizard/Appearance)
  </Step>

  <Step title="Step 3: Knowledge Base">
    Upload files, add FAQs, crawl URLs. Same shape as the Text variant. The agent uses these during calls to answer questions.

    This step is **optional**.

    [Full step reference →](/en/Systems/AI-Agents/Wizard/Knowledge-Base)
  </Step>

  <Step title="Step 4: Tickets & Leads">
    Configure data collection during calls. The **Voice Agent** tab is the active one (the Text Agent tab is hidden for voice-only).

    This step is **optional**.

    [Full step reference →](/en/Systems/AI-Agents/Wizard/Tickets-and-Leads)
  </Step>

  <Step title="Step 5: Integrations & Tools">
    Same as Text variant: marketplace, MCP, agent tools, custom API tools, webhooks.

    This step is **optional**.

    [Full step reference →](/en/Systems/AI-Agents/Wizard/Integrations-and-Tools)
  </Step>

  <Step title="Step 6: Deployment">
    Two tabs (Social is hidden for voice-only): **Website** (embed for the voice widget on a webpage if you want web-initiated calls), **Telephony** (4 provider cards), plus the **Agent Status** card to **Activate**.

    [Full step reference →](/en/Systems/AI-Agents/Wizard/Deployment)
  </Step>
</Steps>

## What the Voice wizard hides (compared to Hybrid)

Hybrid is the superset. Voice trims out:

* **Text Agent Settings** (no chat-only step). The Agent Name field moves into Voice Agent Settings instead.
* The **chat toggle** in the live preview pane. The widget preview always shows the voice view.
* **Chat Screen Text** fields in Appearance.
* The **Social** deployment tab (no WhatsApp / Messenger / Instagram / X / Telegram chat).
* The **Text** tab in Tickets & Leads.

## Telephony providers

The Deployment step gives you four provider cards in a 2-column grid:

| Provider           | Direction                          | Credentials                                            |
| ------------------ | ---------------------------------- | ------------------------------------------------------ |
| **Twilio**         | Inbound / Outbound / Bidirectional | Account SID, Auth Token                                |
| **Telnyx**         | Inbound / Outbound / Bidirectional | API Key                                                |
| **SIP Trunk**      | Inbound / Outbound / Bidirectional | None, system generates a SIP URI you point your PBX at |
| **WhatsApp Calls** | Inbound only (today)               | Phone Number ID, Access Token                          |

Each provider supports up to **10 phone numbers or extensions** with type **phone** or **extension**.

## Test before you ship

Two test surfaces:

1. **In the wizard**, the right-side preview pane shows the voice widget. Click the call button to dial the agent. The first call requires microphone permission for `app.wittify.ai`.
2. **After the first save**, the **Test Your Agent** button is in the topbar of every Manage Agent page. Same flow, but on a real Manage Agent surface. [Read more →](/en/Systems/AI-Agents/Manage-Agent/Test-Your-Agent)

## Activate

When all steps you care about are saved, go to **Step 6: Deployment** and look at the **Agent Status** card. Click **Activate Agent** (green, check icon). The agent goes online and starts answering calls on every connected provider line. Toast: *Agent activated.*

Inbound and bidirectional calls start answering the moment a call lands on a connected number. Outbound campaigns are scheduled separately, see [Outbound Voice Campaigns](/en/Systems/AI-Agents/Manage-Agent/Outbound-Voice-Campaigns).

## Common questions

<AccordionGroup>
  <Accordion title="My voice agent doesn't speak when I test the call.">
    Three checks: (1) you've selected a voice in Step 1's Voice Picker, (2) the Core Instructions are non-empty, (3) microphone permission is granted to `app.wittify.ai`. The widget shows a "Tap to talk" hint when waiting for input.
  </Accordion>

  <Accordion title="The agent talks too fast.">
    Tune **Speaking Speed** in Step 1's **Advanced Voice Settings**. Default is 1.0, lower it to 0.85-0.9 for slower speech. The valid range is 0.5 to 2.0.
  </Accordion>

  <Accordion title="Calls connect but the agent never picks up.">
    Check Step 6's **Agent Status** card, the agent is **Draft** until you click Activate. Activate, place a test call again.
  </Accordion>

  <Accordion title="Twilio rejected my caller ID.">
    Twilio requires verified caller IDs for outbound. In your Twilio console, verify the number you're using as caller ID, then try again from the wizard.
  </Accordion>

  <Accordion title="Can I record calls?">
    Voice calls are recorded by default for transcription and AI summary. Recordings are accessible in [Voice Conversations](/en/Systems/AI-Agents/Manage-Agent/Voice-Conversations) after each call ends.
  </Accordion>

  <Accordion title="Why is the Social deployment tab missing?">
    Voice-only agents can't take chat traffic. The Social tab is hidden because there's nothing to wire. If you ever need chat too, delete this agent and create a Hybrid one.
  </Accordion>
</AccordionGroup>

## Next

<CardGroup cols={2}>
  <Card title="Open Step 1" icon="play" href="/en/Systems/AI-Agents/Wizard/Voice-Settings">
    Start at Voice Agent Settings.
  </Card>

  <Card title="See Voice Conversations" icon="phone" href="/en/Systems/AI-Agents/Manage-Agent/Voice-Conversations">
    Where calls and recordings live.
  </Card>
</CardGroup>