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

# AI & Voice Customization

> Control how your agent sounds, behaves, and responds. Create the perfect AI persona for your use case.

## Creating Your AI Persona

The most important part of your AI agent is the **instructions** (system prompt). This defines who the agent is, what they do, and how they behave.

## Writing Effective Instructions

Your instructions should include:

### 1. Identity & Role

```text theme={null}
You are Rachel, a senior appointment coordinator at Bright Dental.
You have 5 years of experience and are known for being warm and professional.
```

### 2. Goal & Context

```text theme={null}
Your goal is to confirm {{patient_name}}'s appointment scheduled for
{{appointment_date}} at {{appointment_time}}.

The patient has been a client for 3 years and prefers afternoon appointments.
```

### 3. Tone & Style

```text theme={null}
Be warm, professional, and concise. Use the patient's first name naturally.
If they seem rushed, keep it brief. If they want to chat, be friendly but
redirect to the appointment confirmation.
```

### 4. Handling Scenarios

```text theme={null}
- If they want to reschedule: Ask for their preferred date/time and use
  the 'check_availability' tool to find slots.

- If they cancel: Express understanding, ask if everything is okay, but
  do not pressure them. Offer to call back if they change their mind.

- If they have questions: Answer directly or use the 'lookup_patient_info'
  tool if you need specific details.
```

### 5. Boundaries

```text theme={null}
- Never discuss pricing or billing (transfer to billing department)
- Never make medical diagnoses
- Always confirm the appointment details before ending the call
```

## Complete Example

```text theme={null}
You are Rachel, a friendly appointment coordinator at Bright Dental.

Your goal is to confirm {{patient_name}}'s dental appointment scheduled
for {{appointment_date}} at {{appointment_time}}.

Be warm, professional, and concise. Use the patient's first name naturally.

If they want to reschedule:
- Ask for their preferred date and time
- Use the 'check_availability' tool to find available slots
- Confirm the new appointment immediately

If they cancel:
- Express understanding
- Ask if everything is okay (but don't pressure)
- Offer to call back if they change their mind

If they have questions:
- Answer directly if you know the answer
- Use the 'lookup_patient_info' tool for specific patient details
- Transfer to the front desk for complex questions

Never discuss pricing or billing. Always confirm appointment details
before ending the call.
```

## Voice Selection

### Realtime Mode Voices

In Realtime Mode, choose from preset voices optimized for low-latency conversations. The default voice is `alloy`.

Check available voices via `GET /v1/voices/builtin`.

<Note>
  Realtime Mode voices are optimized for ultra-low latency and natural conversation. They work best for English but can handle other languages with proper instructions.
</Note>

### Legacy Mode: Full Voice Library

Legacy Mode gives you access to hundreds of built-in voices plus voice cloning:

* **Large voice library** with voices across different styles and tones
* **Voice cloning**: Upload audio samples to clone any voice
* **Multiple languages** supported
* **Custom voice IDs**: Use any voice from our library

Check available voices via `GET /v1/voices/builtin` and `GET /v1/voices`.

```json theme={null}
{
  "voice": "your-voice-id",
  "mode": "legacy"
}
```

## Language & Dialect Control

### Realtime Mode

* **Auto-detection**: Works automatically but best with explicit instructions
* **Instruction-based**: Tell the AI "Speak only in Spanish" or "Respond in French"

### Legacy Mode

* **Full control**: Set `stt_language` for speech recognition
* **36+ languages**: en-US, en-GB, en-AU, es-ES, es-MX, fr-FR, de-DE, and more
* **Dialect-specific**: Choose British English (`en-GB`) vs American (`en-US`)

```json theme={null}
{
  "mode": "legacy",
  "stt_language": "en-GB",
  "voice": "your-preferred-voice-id"
}
```

## Temperature & Creativity

Control how creative or focused your AI is:

```json theme={null}
{
  "temperature": 0.7
}
```

* **0.0-0.3**: Very focused, consistent responses (good for confirmations)
* **0.4-0.7**: Balanced (default, good for most use cases)
* **0.8-1.0**: Creative, varied responses (good for sales, engaging conversations)

## First Sentence

Set the opening line to control how the call starts:

```json theme={null}
{
  "first_sentence": "Hi {{name}}, this is Rachel from Bright Dental. I'm calling to confirm your appointment tomorrow at 3 PM."
}
```

<Warning>
  The first sentence is critical. It sets the tone and immediately establishes context. Make it clear, friendly, and specific.
</Warning>

## Best Practices

### Do This

* **Be specific**: Include exact scenarios and how to handle them
* **Set boundaries**: Define what the AI should and shouldn't do
* **Use variables**: Use `{{variable}}` syntax for personalization
* **Test thoroughly**: Try different scenarios before going live
* **Iterate**: Refine instructions based on real call transcripts

### Avoid This

* **Vague instructions**: "Be helpful" is too generic
* **Conflicting goals**: Don't ask the AI to both sell and not be pushy without clear boundaries
* **Missing context**: Provide relevant information about the customer or situation
* **Too long**: Keep instructions focused, around 200-500 words

## Next Steps

<CardGroup cols={2}>
  <Card title="Voice Library" icon="microphone" href="/guides/custom-voices">
    Browse available voices and learn about voice cloning.
  </Card>

  <Card title="Function Calling" icon="screwdriver-wrench" href="/guides/function-calling">
    Give your AI tools to interact with your systems mid-call.
  </Card>
</CardGroup>