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

# Voice notes

> The text agent replies with WhatsApp voice notes that sound recorded: when it speaks, how to pick the voice and sound, style guidance, pronunciations, models, costs, limits and guides by type of business.

export const Availability = ({lang = 'es', plan, addon, permission, route, status}) => {
  const L = lang === 'en' ? {
    plan: 'Plan',
    addon: 'Add-on',
    permission: 'Permission',
    route: 'Where',
    status: 'Status',
    addonNote: 'enabled on request',
    allPlans: 'All plans',
    beta: 'Beta',
    nuevo: 'New',
    soon: 'Coming soon'
  } : {
    plan: 'Plan',
    addon: 'Add-on',
    permission: 'Permiso',
    route: 'Dónde',
    status: 'Estado',
    addonNote: 'se activa a pedido',
    allPlans: 'Todos los planes',
    beta: 'Beta',
    nuevo: 'Nuevo',
    soon: 'Próximamente'
  };
  const items = [];
  if (plan) items.push([L.plan, plan]);
  if (addon) items.push([L.addon, `${addon} · ${L.addonNote}`]);
  if (permission) items.push([L.permission, permission]);
  if (route) items.push([L.route, route]);
  if (status) items.push([L.status, L[status] || status]);
  return <div style={{
    display: 'flex',
    flexWrap: 'wrap',
    gap: '6px 22px',
    padding: '12px 16px',
    margin: '4px 0 24px',
    border: '1px solid rgba(2, 82, 255, 0.28)',
    borderLeft: '3px solid #0252ff',
    borderRadius: '8px',
    background: 'rgba(2, 82, 255, 0.05)',
    fontSize: '13.5px',
    lineHeight: '1.5'
  }}>
      {items.map(([k, v]) => <div key={k} style={{
    display: 'flex',
    gap: '6px',
    alignItems: 'baseline'
  }}>
          <span style={{
    fontSize: '10.5px',
    fontWeight: 600,
    letterSpacing: '0.07em',
    textTransform: 'uppercase',
    opacity: 0.65
  }}>{k}</span>
          <span style={{
    fontWeight: 500
  }}>{v}</span>
        </div>)}
    </div>;
};

<Availability lang="en" permission="agents.read; agents.update to edit" route="Agents → Text → Voice" status="nuevo" />

A text agent can reply with **WhatsApp voice notes**: the customer gets an audio message, as if someone at the business had recorded it on their phone. You set it up in the agent's **Voice** tab. ElevenLabs generates the voice, and it's billed per use, on top of the AI message.

## How it works

<Steps>
  <Step title="The customer writes or sends a voice note">
    The agent understands the customer's voice notes just like written messages.
  </Step>

  <Step title="The agent decides whether to speak">
    Depending on the mode you chose (for example, **Mirror**: if the customer sent audio, it replies with audio), the agent writes the reply to be said out loud: short sentences, no lists, links or emojis.
  </Step>

  <Step title="The spoken text is prepared">
    Prices, numbers, dates, times and phone numbers are turned into words the way a person would say them: `$185` becomes "ciento ochenta y cinco pesos", `2:30 p. m.` "las dos y media de la tarde", `10/10` "diez de octubre". Your pronunciations are applied.
  </Step>

  <Step title="The voice and sound are generated">
    ElevenLabs generates the audio with the chosen voice and model. Then it gets the sound you configured: phone microphone, room echo and a soft background, or a call center.
  </Step>

  <Step title="It arrives as a voice note">
    The customer gets a WhatsApp voice note (the microphone kind, not an attached file). If the reply had something worth keeping in writing, like a link or an exact address, it arrives as a text message right after.
  </Step>
</Steps>

A voice note takes a few seconds longer than text: between 1 and 5 extra seconds, depending on length.

## Turn them on

<Steps>
  <Step title="Open the Voice tab">
    In **Agents → Text**, open the agent and go to the **Voice** tab.
  </Step>

  <Step title="Turn on Reply with voice notes">
    The configuration sections appear, with the recommended values: **Mirror** mode, **Phone note** sound and the **v4 Turbo** model.
  </Step>

  <Step title="Pick a voice">
    It's the only required field. Listen to the samples with ▶ and pick one.
  </Step>

  <Step title="Hear how it sounds">
    In the **Hear how it sounds** panel, click **Listen**. The preview uses what's on screen, even if it isn't saved.
  </Step>

  <Step title="Save the tab">
    Click **Save** (or Ctrl + Enter). From then on the agent replies with audio according to the mode.
  </Step>
</Steps>

Saving the **Voice** tab only saves the voice settings. Unsaved changes in **Advanced** or other tabs aren't sent.

## When it replies with audio

| Mode | What it does | When to use it |
| - | - | - |
| **Mirror** (recommended) | If the customer's last message was a voice note, it replies with audio. If they typed, it replies in writing. | Most businesses: each customer gets the format they chose. |
| **Agent decides** | Uses audio when it helps: an explanation, a warm greeting, something empathetic. Data, prices to compare and links go as text. | Friendly brands that want to mix formats. |
| **Always** | Every reply is a voice note. | Brands that want to feel very close, with customers who prefer listening. |

Even when it's time to speak, a reply goes out as text if it has a list, if it's longer than **Max length per note**, or if nothing was left to say. That way a price list or a menu doesn't become a long audio.

## Pick the voice

The catalog shows ElevenLabs' Spanish voices, the most used for conversations.

* **Accent**: Mexico, Colombia, Argentina, Chile, Peru, Venezuela, Spain and neutral. The first time, the accent of the agent's time zone is preselected.
* **Gender**: all, female or male.
* **Sample**: tap ▶ on a voice to hear it. Tapping another one stops the previous one.

### Use another voice

In **Use another voice (ElevenLabs ID)** you can paste the ID of any voice in ElevenLabs' public library and give it a name. Try it with **Listen** before saving: if the ID doesn't exist, the preview tells you.

<Note>
  Voices are generated by ContactShip's ElevenLabs account. A voice cloned in your own ElevenLabs account won't work by ID unless it's published in the public library. If you need your brand's own voice, contact support.
</Note>

## How it sounds

A perfect studio recording gives the machine away. These styles make it sound truly recorded:

| Style | How it sounds | How the agent speaks |
| - | - | - |
| **Phone note** (recommended) | Phone microphone, room echo, the phone's automatic gain and a soft background. It starts with half a second of ambience, like when someone presses record. | More casual, like a WhatsApp voice note, with an occasional soft filler. |
| **Call center** | An agent on a headset with office murmur behind. | Like a support agent: polite, structured and formal ("usted"). |
| **Clean** | Studio voice, no effects. | No added style. |

### Background sound

With **Phone note** or **Call center** you pick the background: **Home**, **Shop / business**, **Office**, **Street**, **Call center**, **No background** or **Custom**. With **Custom** you describe how it sounds, for example "a street taco stand, sizzling griddle and people ordering". English usually works better, with no music or clear voices.

The background is generated once and reused for every note from the agent. The first note with a new background can take a few extra seconds.

**Background volume** goes from **Barely there** to **Clearly present**. The **Natural** point is recommended: you hear the place without covering the voice.

## How it speaks

### Style guidance

Free text, up to 2,000 characters, that the agent follows only when it replies with audio: expressions to use, tone, how it greets or says goodbye, what to avoid. The example buttons add a line ready to edit.

<Tabs>
  <Tab title="Good">
    ```text theme={null}
    Hablá como alguien de Monterrey: usá «va», «sale» y «ándale», sin exagerar.
    Saludá con «¡Qué onda!» solo si el cliente escribe informal.
    Despedite con «¡que te aproveche!» cuando confirmes un pedido.
    Nunca digas «órale».
    ```
  </Tab>

  <Tab title="Better to avoid">
    ```text theme={null}
    Reply with audio when the customer asks about prices.
    ```

    When to reply with audio is set by the **mode**, not the guidance. This field is about how it speaks, not when.
  </Tab>
</Tabs>

You don't need to explain in **Instructions** how to write for voice: ContactShip adds those rules itself when it's time to speak. **Instructions** still apply to the content of the reply.

### Pronunciations

For brands or words the voice gets wrong. In **Written** you enter the word as it appears in messages, and in **Said** how it should sound.

| Written | Said | Why |
| - | - | - |
| Suhicito | Sushicito | The voice said "Sujicito" |
| GoodMed | Gud Med | English brand name |
| Dra. | doctora | Already converted automatically; no need to add it |

* The whole word is replaced, regardless of case: `Suhicito` doesn't change `Suhicitos`.
* It only affects what's said. The chat, the inbox and the history keep the normal spelling.
* Up to 50 pronunciations per agent. Both columns are required.

<Tip>
  Write **Said** the way it sounds, not the correct spelling. If the voice still gets it wrong, try splitting syllables with spaces or changing a letter ("Gud Med", "Sushi sito"), and check it with **Listen**.
</Tip>

## Voice model

| Model | What for | Cost per 1,000 characters | A typical note (\~300 characters, \~20 s) |
| - | - | - | - |
| **v4 Turbo** (recommended) | Natural and very fast. The best balance for chats. | 8 credits (US\$0.08) | \~2.4 credits |
| **v4** | Top quality and expressiveness. | 16 credits (US\$0.16) | \~4.8 credits |
| **Multilingual v2** | Stable and proven, no emotions. | 16 credits (US\$0.16) | \~4.8 credits |

**Emotions**, available with v4 models: the agent can mark the tone of a sentence (warm, cheerful, reassuring, a short laugh) and the voice performs it. It uses at most two per reply and none on sensitive topics like health, complaints or billing. Tone marks don't show up in the chat.

### Fine tuning

| Setting | What it does | Default |
| - | - | - |
| **Stability** | Lower: more expressive and varied. Higher: more even. | 45% |
| **Similarity to the original voice** | How faithful to the sample it sounds. | 80% |
| **Speed** | From 0.70× to 1.20×. 1× is the voice's normal pace. | 1× |
| **Max length per note** | From 100 to 1,200 characters (about 15 characters per second). A longer reply goes out as text. | 600 (about 40 s) |
| **How "\$" is said** | **Automatic** uses pesos by the agent's time zone (Mexico, Colombia, Argentina, Chile, Uruguay, Dominican Republic and Cuba) and dollars elsewhere. You can also force **Pesos** or **Dollars**. `US$` and `USD` are always said as dollars. | Automatic |
| **Data in writing** | Links, addresses or reference numbers are sent as a text message right after the voice note. | On |

## Try it before saving

The **Hear how it sounds** panel generates a note with the settings on screen, saved or not, through the same path as a real note: same spoken text, voice, model and sound.

* Write your own test text, up to 400 characters, or use **Sample text**: it has a price and a time so you hear how they're said.
* Under the player you see **What was said**: the exact text the voice read, with numbers in words and pronunciations applied. That's where you spot anything converted wrong.
* The badges show whether the realistic sound was applied and how much that note would cost in production.
* Previews are free, up to 30 per hour per user.

The **Test agent** sandbox doesn't generate audio: it shows the written reply. To hear the voice, use this panel. See [Test in the sandbox](/en/text-agents/sandbox).

## What your team sees in the inbox

The reply stays in the conversation as an audio message. Along with the audio, the text of what the voice said is stored, `🔊 Nota de voz: «…»`, written normally (with `$185`, not "ciento ochenta y cinco pesos"). That text is what the agent sees in its history, so it remembers what it said.

If ElevenLabs can't generate the audio, it's tried up to three times. If it keeps failing, the customer gets the same content as a text message and the voice isn't charged. If only the sound effect fails, the note goes out clean.

## Costs

* The voice is billed per spoken character, by model, as in the table above. It's deducted from the organization's credit balance (1 credit = US\$0.01).
* It's only charged when the note was sent. If it went out as text because of an error, the voice isn't charged.
* The AI message is billed as usual, separately from the voice.
* **Hear how it sounds** previews are free.

See [Credits and payments](/en/billing/credits-and-payments).

## What you can and can't do

| You can | You can't (yet) |
| - | - |
| Reply with audio in WhatsApp Business conversations. | Voice notes on other channels: there the same reply goes out as text. |
| Mix audio and text: the audio, then the data in writing right after. | Show "recording audio…" while it's generated. The WhatsApp Business API only allows the "typing…" indicator. |
| Use any voice from ElevenLabs' public library by its ID. | Clone a voice from the app or use a private voice from another ElevenLabs account. |
| A different setup per agent: voice, sound, style and pronunciations. | Send automatic **follow-ups** or **templates** as audio: they always go as text. |
| Hear the result before saving. | Hear audio in the **Test agent** sandbox. |
| Notes up to 1,200 characters (about 80 seconds). | Longer notes: the reply goes out as text. |
| Ambience backgrounds: home, shop, office, street, call center or a described one. | Music or sound effects on request inside a note. |

## Guides by type of business

<Tabs>
  <Tab title="Restaurant or delivery">
    * **Mode**: Mirror.
    * **Voice**: a warm one from the business's country.
    * **Sound**: Phone note, **Shop / business** background, Natural volume.
    * **Model**: v4 Turbo, with emotions.
    * **Guidance**:
      ```text theme={null}
      Sonás como quien atiende el local. Confirmá el pedido en una sola frase y el tiempo de entrega.
      Usá expresiones de la ciudad, sin exagerar. Despedite con buena onda.
      ```
    * **Pronunciations**: the shop's name and dishes with proper names.
    * **Data in writing**: on, to send the payment link or location.
  </Tab>

  <Tab title="Clinic or practice">
    * **Mode**: Mirror.
    * **Voice**: calm and clear; raise **Stability** to 55–65%.
    * **Sound**: Phone note with an **Office** background at Subtle volume, or **Call center**.
    * **Model**: v4 Turbo. The agent is told not to use emotions on health topics; to be sure, turn **Emotions** off.
    * **Guidance**:
      ```text theme={null}
      Tratá de usted. Nunca des diagnósticos ni indicaciones médicas por audio.
      Confirmá fecha, hora y profesional del turno, y que la dirección va por escrito.
      ```
    * **Pronunciations**: names of professionals and the clinic if they're in another language.
  </Tab>

  <Tab title="Support or call center">
    * **Mode**: Agent decides, to explain with audio and send steps and links as text.
    * **Sound**: **Call center**, Call center background.
    * **Guidance**:
      ```text theme={null}
      Presentate como del equipo de soporte. Explicá en no más de tres frases.
      Si hay pasos a seguir, decí que van por escrito.
      ```
    * **Max length**: 400 to 600 characters, so the notes don't get long.
  </Tab>

  <Tab title="Brand with a hard name">
    1. Write a sentence with the brand name in the preview panel and listen to it.
    2. If it sounds wrong, add the pronunciation: **Written** is the real name, **Said** is how it should sound.
    3. Listen again. Check **What was said** to confirm the replacement was applied.
    4. Repeat with products or places the agent mentions often.
  </Tab>
</Tabs>

## Best practices

* **Start with Mirror.** Customers who send voice notes usually prefer listening; those who type, reading.
* **Pick a voice that matches the agent's persona.** If the agent introduces itself as "Sofía from Monterrey", use a female Mexican voice.
* **Test with your real messages.** Prices, times, addresses and proper names are what stand out most when they come out wrong.
* **Watch the background volume.** Natural sounds real; Loud can be annoying in long notes.
* **Keep notes short.** Two or three sentences get listened to in full; long content is better in writing.

## Troubleshooting

| Symptom | Cause | Fix |
| - | - | - |
| The agent doesn't reply with audio | In **Mirror** mode, the customer typed instead of sending audio. Or the conversation isn't on WhatsApp Business. | That's expected. To test, send a voice note from WhatsApp to the channel's number. |
| It replied with text to a voice note | The reply had a list or was longer than **Max length per note**. | Raise the max length or ask for shorter replies in **Style guidance**. |
| It mispronounces a word | The voice doesn't know the brand or name. | Add it under **Pronunciations** and check it with **Listen**. |
| It says "dólares" instead of "pesos" | The agent's time zone isn't in a peso country. | Set the time zone in **General** or force **Pesos** in **How "\$" is said**. |
| It sounds too perfect, robotic | Sound is set to **Clean**. | Pick **Phone note** and a background. |
| The background covers the voice | Volume too high. | Lower it to **Natural** or **Subtle**. |
| **ElevenLabs doesn't recognize that voice or setting** | The voice ID doesn't exist or is private to another account. | Pick a catalog voice or use an ID from the public library. |
| **You reached the hourly preview limit** | You ran 30 previews in the last hour. | Wait a while. Real notes don't have this limit. |
| The customer got text with the audio's content | ElevenLabs didn't respond after three attempts. | The next reply tries voice again. If it keeps happening, contact support. That voice wasn't charged. |

## FAQ

<AccordionGroup>
  <Accordion title="Will the customer notice it's an AI?">
    The voice and the phone sound are meant to sound natural, but they don't hide anything: the conversation is still with the AI agent you configured. If your business discloses that a virtual assistant answers, keep that notice in **Instructions**.
  </Accordion>

  <Accordion title="Can each agent have its own voice?">
    Yes. Each agent has its own **Voice** tab with voice, sound, style and pronunciations.
  </Accordion>

  <Accordion title="Does the agent understand the customer's voice notes?">
    Yes, even with voice notes turned off. Turning them on only changes how it replies.
  </Accordion>

  <Accordion title="What about conversations that were already open?">
    Once you save, the agent applies the settings in its next reply, also in open conversations.
  </Accordion>

  <Accordion title="How much does it cost per month?">
    It depends on how many replies go out as audio and how long they are. With **v4 Turbo**, 1,000 notes of about 20 seconds cost about 2,400 credits (US\$24), on top of the AI messages. **Mirror** mode limits audio to customers who send audio.
  </Accordion>

  <Accordion title="Can my team send voice notes?">
    Yes, from the inbox, recording them as usual. The **Voice** tab only configures the AI agent's replies. See [Inbox](/en/messages/inbox).
  </Accordion>
</AccordionGroup>

## See also

<CardGroup cols={2}>
  <Card title="Create a text agent" href="/en/text-agents/create" />

  <Card title="Instructions" href="/en/text-agents/instructions" />

  <Card title="Test in the sandbox" href="/en/text-agents/sandbox" />

  <Card title="Credits and payments" href="/en/billing/credits-and-payments" />
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.