Skip to content

Commit bcb0074

Browse files
adhamvapiclaude
adhamvapi
and
claude
committed
docs: add API configuration section for email formatting
Expand the email address reading guide with a technical API configuration section covering: - Full 14-step voice formatting pipeline table showing where formatEmails (step 8) fits - FormatPlan TypeScript type definition - Code examples (JSON, TypeScript SDK, Python SDK) for enabling specific formatters, disabling email formatting selectively, and disabling all formatting - Note on formattersEnabled introduction date (2025-02-20) - Updated overview to describe three solution layers (built-in formatting, API configuration, prompt engineering) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
1 parent 1a850fc commit bcb0074

1 file changed

Lines changed: 174 additions & 6 deletions

File tree

‎fern/assistants/email-address-reading.mdx‎

Lines changed: 174 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -8,24 +8,191 @@ slug: assistants/email-address-reading
88

99
Email addresses are one of the trickiest pieces of information for a voice agent to handle. They contain special characters (`@`, `.`, `-`, `_`), mixed-case text, and domain names that text-to-speech (TTS) engines often mispronounce or blur together when spoken aloud.
1010

11-
This guide covers two sides of the problem:
11+
This guide covers three layers of the solution:
1212

13-
- **Built-in formatting** -- Vapi automatically transforms email characters for TTS so they sound natural.
13+
- **Built-in formatting** -- Vapi automatically transforms email characters for TTS so they sound natural, with zero configuration.
14+
- **API configuration** -- You can fine-tune which formatters run, disable email formatting selectively, or customize the entire formatting pipeline.
1415
- **Prompt engineering** -- You instruct the LLM *how* to collect, read back, and confirm emails in conversation so users feel confident their address was captured correctly.
1516

1617
## How Vapi handles emails automatically
1718

18-
Vapi's [voice formatting plan](/assistants/voice-formatting-plan) includes a built-in `formatEmails` step that runs before text reaches the TTS provider. It replaces `@` with "at" and `.` with "dot" so the spoken output is intelligible without any prompt changes.
19+
Vapi's [voice formatting plan](/assistants/voice-formatting-plan) runs a 14-step pipeline that transforms raw LLM text into natural-sounding speech before it reaches the TTS provider. The `email` formatter is **step 8** in this pipeline. It replaces `@` with "at" and `.` with "dot" so the spoken output is intelligible without any prompt changes.
1920

2021
| Raw LLM output | What the user hears |
2122
|---|---|
2223
| `john.doe@example.com` | "john dot doe at example dot com" |
2324
| `SALES@company.org` | "SALES at company dot org" |
25+
| `jane_smith-work@my-company.co.uk` | "jane underscore smith dash work at my dash company dot co dot uk" |
2426

2527
<Tip>
26-
The `formatEmails` formatter is enabled by default. You do not need to configure anything for basic email reading to work. The rest of this guide focuses on the **prompt-level techniques** that make the full collection-and-confirmation flow reliable.
28+
The `email` formatter is enabled by default. You do not need to configure anything for basic email reading to work.
2729
</Tip>
2830

31+
### Where email formatting fits in the pipeline
32+
33+
The formatter runs after acronym and dollar-amount formatting, and before date, time, and phone number formatting. Here is the full 14-step pipeline with the email step highlighted:
34+
35+
| Step | Formatter key | What it does | Default |
36+
|------|--------------|--------------|---------|
37+
| 1 | `removeAngleBrackets` | Removes `<...>` tags (except `<break>`, `<spell>`, `<< >>`) | On |
38+
| 2 | `markdown` | Removes markdown symbols (`_`, `` ` ``, `~`) | On |
39+
| 3 | `asterisk` | Removes text wrapped in `*` or `**` | Off |
40+
| 4 | `newline` | Converts `\n` to `.` for smoother phrasing | On |
41+
| 5 | `colon` | Replaces `:` with `.` | On |
42+
| 6 | `acronym` | Formats acronyms (e.g., `NASA` to `nasa`) | On |
43+
| 7 | `dollarAmount` | `$42.50` to "forty two dollars and fifty cents" | On |
44+
| **8** | **`email`** | **`@` to "at", `.` to "dot" in email addresses** | **On** |
45+
| 9 | `date` | `2023-05-10` to "Wednesday, May 10, 2023" | On |
46+
| 10 | `time` | `14:00` to "14" | On |
47+
| 11 | `distance` / `unit` / `percentage` | `5km` to "5 kilometers", `50%` to "50 percent" | On |
48+
| 12 | `phoneNumber` | `123-456-7890` to "1 2 3 4 5 6 7 8 9 0" | On |
49+
| 13 | `number` | Formats general numbers, years, decimals | On |
50+
| 14 | `stripAsterisk` | Removes remaining `*` characters | On |
51+
52+
<Note>
53+
For full details on every step, see the [voice formatting plan](/assistants/voice-formatting-plan) reference.
54+
</Note>
55+
56+
## Configuring email formatting via the API
57+
58+
The email formatter runs automatically with no configuration needed. However, you can customize the behavior through the `formatPlan` on your assistant's voice configuration.
59+
60+
### Configuration path
61+
62+
```
63+
assistant.voice.chunkPlan.formatPlan
64+
```
65+
66+
The relevant TypeScript type:
67+
68+
```typescript title="FormatPlan type definition"
69+
interface FormatPlan {
70+
enabled?: boolean; // default: true
71+
numberToDigitsCutoff?: number; // default: 2025
72+
replacements?: FormatPlanReplacementsItem[]; // default: []
73+
formattersEnabled?: FormatPlanFormattersEnabledItem[]; // default: all formatters
74+
}
75+
```
76+
77+
The `formattersEnabled` array accepts any combination of these values: `removeAngleBrackets`, `markdown`, `asterisk`, `newline`, `colon`, `acronym`, `dollarAmount`, `email`, `date`, `time`, `distance`, `unit`, `percentage`, `phoneNumber`, `number`, `stripAsterisk`.
78+
79+
<Note>
80+
The `formattersEnabled` property was introduced on **2025-02-20**. Before that date, you could only toggle all formatting on or off with the `enabled` flag. If you are using an older API version, use `enabled: false` to disable all formatting.
81+
</Note>
82+
83+
### Default behavior (no configuration needed)
84+
85+
By default, all formatters -- including `email` -- are enabled. You do not need to set anything for email addresses to be read correctly:
86+
87+
```json title="Default -- email formatting is already on"
88+
{
89+
"voice": {
90+
"chunkPlan": {
91+
"formatPlan": {
92+
"enabled": true
93+
}
94+
}
95+
}
96+
}
97+
```
98+
99+
### Enable only specific formatters
100+
101+
If you want tight control over which transformations run, pass only the formatter keys you need. This example enables only the `email` and `phoneNumber` formatters:
102+
103+
<CodeBlocks>
104+
```json title="JSON (API / Dashboard)"
105+
{
106+
"voice": {
107+
"chunkPlan": {
108+
"formatPlan": {
109+
"formattersEnabled": ["email", "phoneNumber"]
110+
}
111+
}
112+
}
113+
}
114+
```
115+
```typescript title="TypeScript SDK"
116+
const assistant = await vapi.assistants.create({
117+
// ... other configuration
118+
voice: {
119+
chunkPlan: {
120+
formatPlan: {
121+
formattersEnabled: ["email", "phoneNumber"]
122+
}
123+
}
124+
}
125+
});
126+
```
127+
```python title="Python SDK"
128+
assistant = client.assistants.create(
129+
# ... other configuration
130+
voice={
131+
"chunkPlan": {
132+
"formatPlan": {
133+
"formattersEnabled": ["email", "phoneNumber"]
134+
}
135+
}
136+
}
137+
)
138+
```
139+
</CodeBlocks>
140+
141+
<Warning>
142+
When you set `formattersEnabled`, **only** the listed formatters run. All others are disabled. Make sure to include every formatter you need.
143+
</Warning>
144+
145+
### Disable email formatting while keeping all others
146+
147+
Omit `email` from the `formattersEnabled` array. The TTS provider will then receive the raw `@` and `.` characters, and pronunciation depends entirely on the provider and your prompt:
148+
149+
```json title="All formatters except email"
150+
{
151+
"voice": {
152+
"chunkPlan": {
153+
"formatPlan": {
154+
"formattersEnabled": [
155+
"removeAngleBrackets",
156+
"markdown",
157+
"newline",
158+
"colon",
159+
"acronym",
160+
"dollarAmount",
161+
"date",
162+
"time",
163+
"distance",
164+
"unit",
165+
"percentage",
166+
"phoneNumber",
167+
"number",
168+
"stripAsterisk"
169+
]
170+
}
171+
}
172+
}
173+
}
174+
```
175+
176+
### Disable all formatting
177+
178+
To send raw LLM output directly to TTS with no transformations at all:
179+
180+
```json title="Disable all formatting"
181+
{
182+
"voice": {
183+
"chunkPlan": {
184+
"formatPlan": {
185+
"enabled": false
186+
}
187+
}
188+
}
189+
}
190+
```
191+
192+
<Warning>
193+
Disabling all formatting means numbers, currencies, dates, phone numbers, and emails will all be sent raw to the TTS provider. Most providers will produce unnatural or garbled speech for these patterns.
194+
</Warning>
195+
29196
## Why prompt engineering still matters
30197

31198
Even though TTS formatting handles the character-level pronunciation, the LLM still controls *how* the conversation flows. Without explicit instructions, the agent might:
@@ -261,7 +428,8 @@ For example, if users frequently mention their company email domain "contoso.com
261428

262429
Now that your agent handles email addresses reliably:
263430

431+
- **[Voice formatting plan](/assistants/voice-formatting-plan)** -- Full reference for all 14 formatting steps and customization options.
264432
- **[Prompting guide](/prompting-guide)** -- General techniques for writing effective voice AI prompts.
265-
- **[Voice formatting plan](/assistants/voice-formatting-plan)** -- Understand and customize how Vapi formats text for TTS.
266-
- **[Pronunciation dictionaries](/assistants/pronunciation-dictionaries)** -- Fine-tune pronunciation for specific words and names.
433+
- **[Pronunciation dictionaries](/assistants/pronunciation-dictionaries)** -- Fine-tune TTS pronunciation for specific words and names.
267434
- **[Custom keywords](/customization/custom-keywords)** -- Improve transcription accuracy for specific terms.
435+
- **[Speech configuration](/customization/speech-configuration)** -- Configure endpointing, silence detection, and other speech settings.

0 commit comments

Comments
 (0)